home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 51
/
Amiga Format CD51 (2000-03-10)(Future Publishing)(GB)[!][issue 2000-04].iso
/
-in_the_mag-
/
workbench
/
term_4.8
/
extras
/
source
/
gtlayout-source.lha
/
gtlayout.doc
< prev
next >
Wrap
Text File
|
1997-09-22
|
131KB
|
3,873 lines
TABLE OF CONTENTS
gtlayout.library/--background--
gtlayout.library/--version--
gtlayout.library/LT_Activate
gtlayout.library/LT_BeginRefresh
gtlayout.library/LT_BuildA
gtlayout.library/LT_CatchUpRefresh
gtlayout.library/LT_CreateHandleTagList
gtlayout.library/LT_DeleteHandle
gtlayout.library/LT_DeleteWindowLock
gtlayout.library/LT_DisposeMenu
gtlayout.library/LT_EndGroup
gtlayout.library/LT_EndRefresh
gtlayout.library/LT_Exit
gtlayout.library/LT_FindMenuCommand
gtlayout.library/LT_GetAttributesA
gtlayout.library/LT_GetCode
gtlayout.library/LT_GetIMsg
gtlayout.library/LT_GetMenuItem
gtlayout.library/LT_GetWindowUserData
gtlayout.library/LT_HandleInput
gtlayout.library/LT_Init
gtlayout.library/LT_LabelChars
gtlayout.library/LT_LabelWidth
gtlayout.library/LT_LayoutMenusA
gtlayout.library/LT_LevelWidth
gtlayout.library/LT_LockWindow
gtlayout.library/LT_MenuControlTagList
gtlayout.library/LT_NewA
gtlayout.library/LT_NewLevelWidth
gtlayout.library/LT_NewMenuTagList
gtlayout.library/LT_NewMenuTemplate
gtlayout.library/LT_PressButton
gtlayout.library/LT_RebuildTagList
gtlayout.library/LT_Refresh
gtlayout.library/LT_ReplyIMsg
gtlayout.library/LT_SetAttributesA
gtlayout.library/LT_ShowWindow
gtlayout.library/LT_UnlockWindow
gtlayout.library/LT_UpdateStrings
gtlayout.library/--background-- gtlayout.library/--background--
NOTES
1. General information
1.1 Purpose
The GUI code included in this archive helps to create user interfaces
using gadtools.library with a minimum of effort. The code
automatically takes care of the font to be used, making the user
interface font independent. Localizing support is built right into
the code, just install a callback hook and pass numeric IDs for the
gadget labels: the code will invoke your hook in order to get the
text required. Keystroke activation of gadgets is also taken care
of, in fact the code will -- unless told not to do so -- assign keyboard
shortcuts to the gadgets created all on its own. Every effort has been
made to make the code reentrant, so it can be put into a shared library.
If a user interface does not fit onto a screen provisions are made to
choose a smaller font and to rescale the window contents until they fit.
Last but not least the user interface code offers transparent extensions
to the standard gadtools.library objects, such as LISTVIEW_KIND objects
which respond to double-clicks or STRING_KIND objects which can be used
to enter password text as they will not display the characters entered.
1.2 Distribution
The code is *free*, you don't need to pay any money to use it, nor
do you need to quote my name in the documentation, the program or
anywhere else. You are allowed to make changes to the code, but if
you stumble across any bugs or even know how to fix them, please
let me know. It does not matter whether you intend to sell a program
to use the code, use the code in shareware, gift-ware, freeware or
etc.-ware programs: the code still remains royalty-free.
1.3 Caveats
The code is pretty large, about 80K-100K bytes in size. Not all
gadtools.library type objects are supported, notably
GENERIC_KIND objects. The code is not as flexible as
gadtools.library, so certain things which are easily done using
gadtools.library may be pretty difficult or even impossible.
The code is written entirely in `C' and requires SAS/C to
compile. Some parts of the code are highly recursive; I haven't
tested how much stack they might require in certain cases,
but I recommend that you don't overuse the grouping feature.
The data structures required to create and maintain the
user interface are huge, a single window might require more
than 4K-6K of memory. Proportional font support only works
well starting with Kickstart v39 and up, v2.04 will probably
not look quite that pretty.
2. Programming
2.1 Client libraries required for link library version
You need to have SysBase and GadToolsBase initialized in order to make
use of the code, i.e. your code has to do
WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes
use of the memory pools introduced in exec.library v39, but calls the
equivalent routines in amiga.lib. Note: as of this writing the pools
code in amiga.lib v40.14 is broken, so you need to link with Mike
Sinz' fixed pools.lib.
2.2 Invocation procedure
The typical invocation procedure looks roughly like this:
LT_Init(); // only for link library version
:
:
LT_CreateHandleTags();
LT_New();
:
:
LT_New();
LT_Build();
LT_HandleInput();
LT_DeleteHandle();
:
:
LT_Exit(); // only for link library version
You need to call LT_Init() only once in your program, it will initialize
the libraries and global data structures required by the user interface
code. When you are finished with the user interface and your program is
about to exit you need to call LT_Exit() or memory will get lost.
Note that LT_Init() is not protected against multiple invocations. If
called repeatedly memory will get lost which can never be reclaimed.
However, LT_Exit() is protected against multiple invocations, you can
also call it before ever giving LT_Init() a call, but I doubt this
would make much sense. If you are using the shared gtlayout.library
no call to LT_Init()/LT_Exit() is necessary as these calls are already
wrapped into the library opening code.
Before you can actually start building a window layout a call to
LT_CreateHandleTags() needs to be made. You need to pass in a pointer
to the Screen your user interface window is to be opened on and,
optionally, a few tags to control the look and performance of the
interface. *Never* close the screen in question before calling
LT_DeleteHandle() or nasty things will happen. For public screens
the code will try to lock the screen in question. With the handle
LT_CreateHandleTags() returned you can call LT_New() to build the
user interface. When finished a call to LT_Build() will finally
open a window and place the gadgets inside. A pointer to the
Window created will be returned, ready to be used for the
WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg()
loop. When finished, a call to LT_DeleteHandle() will close the
window and release all the memory associated with it. The design
of the interface code is similar to the corresponding calls in
gadtools.library, i.e. you don't need to worry about LT_New()
failing to allocate memory for the objects required. When it comes
to LT_Build() the code will know about any trouble which would
show up during previous invocations of LT_New(). In essence,
if LT_Build() returns NULL something is wrong.
2.3 Hierarchic grouping
The basic building block of the user interface is a group, either
a horizontal or a vertical group. Adding gadgets or other objects
to a horizontal group will place them side by side from left to
right. A vertical group causes objects to be place from top to
bottom in one straight line. Groups help to arrange objects
neatly stacked, centered and properly aligned with other
members of the group.
MUCHO IMPORTANTE: there is a bug lurking in the code which I never
had the luck to find and fix. One would expect to create
user interface structures like this:
<group start>
<button>
<list>
<group start>
<slider>
<text>
<group end>
<button>
<group end>
However, it is in fact not possible to mix gadgets and groups.
Thus, the user interface structure would have to look like this:
<group start>
<group start>
<button>
<list>
<group end>
<group start>
<slider>
<text>
<group end>
<group start>
<button>
<group end>
<group end>
Or in other words: groups only mix with other groups.
You build groups using three different object types. In this
context `object type' refers to a specific numeric value the
LT_New() routine knows which will cause it to add another leaf
to the user interface structure tree. Here is an example:
struct LayoutHandle *Handle;
if(Handle = LT_CreateHandleTags(NULL,
LAHN_AutoActivate,FALSE,
TAG_DONE))
{
struct Window *Window;
LT_New(Handle,
LA_Type, VERTICAL_KIND, /* A vertical group. */
LA_LabelText, "Main group", /* Group title text. */
TAG_DONE);
{
LT_New(Handle,
LA_Type, BUTTON_KIND, /* A plain button. */
LA_LabelText, "A button",
LA_ID, 11,
TAG_DONE);
LT_New(Handle,
LA_Type, XBAR_KIND, /* A separator bar. */
TAG_DONE);
LT_New(Handle,
LA_Type, BUTTON_KIND, /* A plain button. */
LA_LabelText, "Another button",
LA_ID, 22,
TAG_DONE);
LT_New(Handle,
LA_Type, END_KIND, /* This ends the current group. */
TAG_DONE);
}
if(Window = LT_Build(Handle,
LAWN_Title, "Window title",
LAWN_IDCMP, IDCMP_CLOSEWINDOW,
WA_CloseGadget, TRUE,
TAG_DONE))
{
struct IntuiMessage *Message;
ULONG MsgQualifier,
MsgClass;
UWORD MsgCode;
struct Gadget *MsgGadget;
BOOL Done = FALSE;
do
{
WaitPort(Window->UserPort);
while(Message = GT_GetIMsg(Window->UserPort))
{
MsgClass = Message->Class;
MsgCode = Message->Code;
MsgQualifier = Message->Qualifier;
MsgGadget = Message->IAddress;
GT_ReplyIMsg(Message);
LT_HandleInput(Handle,MsgQualifier,&MsgClass,
&MsgCode,&MsgGadget);
switch(MsgClass)
{
case IDCMP_CLOSEWINDOW:
Done = TRUE;
break;
case IDCMP_GADGETUP:
switch(MsgGadget->GadgetID)
{
case 11: printf("First gadget\n");
break;
case 22: printf("Second gadget\n");
break;
}
break;
}
}
}
while(!Done);
}
LT_DeleteHandle(Handle);
}
The example creates one single group, places a few objects inside,
calls the layout routine, handles the input and finally cleans
things up again. This example also shows that you *need* at
least one group in your tree (to form the root) in order to get
things to work.
The input loop requires you to call LT_HandleInput() in order
to get the user interface code to filter out certain events and
to update internal information. The data passed in must have
been processed via the gadtools.library routines. You *must not*
call LT_HandleInput() before GT_ReplyIMsg() is called since the
routine may call intuition.library and gadtools.library routines
which in turn might lead to a system lock-up if the message
has not been processed yet. The first thing to do after LT_HandleInput()
has done whatever was necessary to the data you passed in is
examine the MsgClass variable. The user interface code will
`fake' certain message events using the variables passed in,
*do not* use any other data gathered from the original
IntuiMessage. The MsgClass may include event types you did
not ask for, i.e. the IDCMP flags of the window opened
will be set according to the objects you added to the window.
Also, the IDCMP_IDCMPUPDATE message class will show up for
certain objects. More on this later in this document.
2.4 Setting and getting object attributes
The mechanism to update and query object attributes does not
exactly match the familiar gadtools.library interface. In
fact, the routine to change gadget attributes will forward
the tagitem list passed in to gadtools.library/GT_SetGadgetAttrs().
On the other hand the routine to query object attributes does
not work like gadtools.library/GT_GetGadgetAttrs(). The
user interface code assumes that all objects it can handle and
create posess certain attributes unique to the type of the
object in question. For example, the unique attribute of a
STRING_KIND object would be a pointer to the string it
`contains'. The unique attribute of a SLIDER_KIND object is
the current slider position. The LT_GetAttributes() routine
will return this attribute, but also accept a tagitem list
to fill in for certain special tag values.
2.5 Extra data
Once a LayoutHandle has been created the interface code will
provide you with a number of information concerning the screen
the handle has been attached to. This information includes
the DrawInfo structure of the screen, the VisualInfo data
and the Screen address. This information is read-only.
2.6 Menus
With a LayoutHandle available a routine called LT_LayoutMenuTags()
will create a standard Intuition menu structure via gadtools.library
which can be passed to LT_Build(). Note that this
routine does not modify any data passed in, it does neither
attach the menu created to the LayoutHandle passed in,
nor does it change the NewMenu table.
2.7 Localization
All object and menu creation routines support localization via
a Hook callback interface, i.e. you can pass a pointer to an
initialized Hook structure to LT_CreateHandleTags() which will
later be used to supply label and list text for objects
created. The Hook callback routine is called in the following
fashion:
String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,LONG ID)
D0 A0 A2 A1
Or in other words: a locale string ID is passed in, the routine is supposed
to look up the string to match this ID and to return it.
2.8 Object types to generate IDCMP_IDCMPUPDATE events
Certain objects convey extra information which is merged into the `fake'
input stream passed to the client calling LT_HandleInput(). These objects
are:
STRING_KIND
TEXT_KIND
PALETTE_KIND
The user pressed the `select' button which belongs
to this gadget. The MsgGadget pointer indicates the
STRING_KIND/TEXT_KIND/PALETTE_KIND object the `select'
button belongs to.
LISTVIEW_KIND
The user double-clicked on an entry. The entry number
is returned in the MsgCode variable. The MsgGadget
pointer indicates the LISTVIEW_KIND object the user
has clicked on.
2.9 Keystroke activation
Unless forbidden via the the LA_NoKey tag item the user interface
code will pick the keyboard shortcuts for all gadgets on its own.
The currently active global console keymap will be checked at the
time when LT_Init() is called in order to make sure subsequent
calls to LT_Build() will use only keys the user can press on
the keyboard. Double-dead keys are also excluded from the
table created. This avoids problems with gadget labels such as
"éééé" which would require the user to hit two keys in a row to
activate the gadget.
If the window created happens to feature a close gadget
pressing the `Esc' key will cause the client to receive
an IDCMP_CLOSEWINDOW event.
A single LISTVIEW_KIND object may receive special treatment
if the LALV_CursorKey tag is used: the user will be able to
operate the listview using the cursor keys. Note: this
will also keep the user interface code from choosing a
special keystroke from the gadget label.
The user will be able to operate a single BUTTON_KIND
object using the return key if the LABT_ReturnKey tag is
used. A recessed frame will be drawn around the button hit
box to indicate its special status.
Pressing the Tab key can be bound to operate a cycle or
mx kind object.
3. Credits
The original design is based upon the user interface layout code used by
`term' 3.1. I put the first version of the layout routines together back
in Summer 1993 when I wanted to write the follow-up to `term' v3.4.
Martin Taillefer rewrote large parts of the code, added new routines and
generally improved the performance of the layout process. I owe Martin
much for the ideas he put into the library.
Kai Iske, Christoph Feck, Stefan Becker, Michael Barsoom, Sven Stullich
and Mark Ritter helped to iron out the remaining bugs and piled up bug
reports and enhancement requests.
gtlayout.library/--version-- gtlayout.library/--version--
NOTES
This document describes gtlayout.library v5.12 or higher. Do not assume that
previous library releases support the same features.
gtlayout.library/LT_Activate gtlayout.library/LT_Activate
NAME
LT_Activate -- Activate a string type gadget.
SYNOPSIS
LT_Activate(Handle,ID);
A0 D0
VOID LT_Activate(LayoutHandle *,LONG);
FUNCTION
The equivalent to intuition.library/ActivateGadget().
INPUTS
Handle - Pointer to LayoutHandle structure.
ID - ID of Gadget to activate.
RESULT
none
SEE ALSO
intuition.library/ActivateGadget
gtlayout.library/LT_BeginRefresh gtlayout.library/LT_BeginRefresh
NAME
LT_BeginRefresh -- Optimized window refreshing
SYNOPSIS
LT_BeginRefresh(Handle)
A0
FUNCTION
If you wish to handle window refreshing all on your own, you
might want to use the LT_BeginRefresh...LT_EndRefresh pair
in your program. By default the user interface layout engine
will automatically intercept IDCMP_REFRESHWINDOW events and
react to them accordingly.
INPUTS
Handle - Pointer to a LayoutHandle structure.
RESULT
none
SEE ALSO
intuition.library/BeginRefresh
intuition.library/EndRefresh
gtlayout.library/LT_EndRefresh
gtlayout.library/LT_BuildA gtlayout.library/LT_BuildA
NAME
LT_BuildA -- turn the user interface specs into a window
and gadgets.
SYNOPSIS
Window = LT_BuildA(Handle,Tags);
D0 A0 A1
struct Window *LT_BuildA(LayoutHandle *,struct TagItem *);
Window = LT_Build(Handle,...);
struct Window *LT_Build(LayoutHandle *,...);
FUNCTION
This is the big one. After building up a user interface specification
using LT_NewA() a call to LT_BuildA() will finally lay out the single
user interface elements, open a window and put the gadgets, etc.
inside.
The code tries to fit all the gadgets into the window, but if it
runs out of space it will fall back to a different font and
rescale the user interface objects to match it. It will first
fall back onto the system default font. If unsuccessful it will
as a last resort try to use topaz.font/8.
To make it easier to distinguish between different handles that
share the same Window->UserPort, the Window->UserData pointer
will point to the LayoutHandle that created it (V13).
NOTE: Earlier library releases did not support this feature,
so be prepared to deal with Window->UserData == NULL.
INPUTS
Handle - Pointer to a LayoutHandle structure.
Tags - Pointer to TagItem list controlling window
and layout attributes.
All the tag values given are passed straight away to OpenWindowTags(),
see intuition.doc for more information.
In addition to this a number of private tag values are supported:
LAWN_Menu (struct Menu *) - The menu to attach to the window. The
IDCMP flags will be updated to include IDCMP_MENUPICK if this
tag is used.
LAWN_MenuTemplate (struct NewMenu *) - A list of filled-in
NewMenu structures which will get passed straight through
to LT_NewMenuTemplate(). If a menu could be created, it will
be attached to the window. LT_DeleteHandle() will then later
automatically dispose of the menu. Please note that the window
may fail to open due to the menu layout going wrong. Separate
calls to LT_NewMenuTemplate() and LT_Build() may be a better
approach since it is easier to find out which process went
wrong. You will find a pointer to the menu attached to the
LayoutHandle in LayoutHandle->Menu. Please note that this
entry only exists in LayoutHandles created by gtlayout.library
v13 or higher. (V13)
NOTE: This tag effectively overrides LAWN_Menu.
LAWN_MenuTags (struct TagItem *) - A list of TagItems which
will get passed straight through to LT_NewMenuTagList().
Even if you don't ask for it, LT_Build() will pass
"LAMN_Handle,<Handle>" in for you, so any additional tags
specifying screen, fonts, etc. will be overridden. If a menu
could be created, it will be attached to the window.
LT_DeleteHandle() will then later automatically dispose of the
menu. Please note that the window may fail to open due to the
menu layout going wrong. Separate calls to LT_NewMenuTagList()
and LT_Build() may be a better approach since it is easier to
find out which process went wrong. You will find a pointer to the
menu attached to the LayoutHandle in LayoutHandle->Menu. Please note
that this entry only exists in LayoutHandles created by
gtlayout.library v13 or higher. (V13)
NOTE: This tag effectively overrides LAWN_Menu and has
precedence over LAWN_MenuTemplate.
LAWN_UserPort (struct MsgPort *) - The MsgPort to use as the
window user port. The MsgPort will be attached using the
common ModifyIDCMP() method, closing the window will
first remove and reply all pending messages at this port.
LAWN_Left (LONG) - The left edge position the window is to use.
This effectively overrides any horizontal alignment flags.
NOTE: the code may choose to ignore this value if it finds
that the window will not fit onto the screen unless
the left edge position is changed.
LAWN_Top (LONG) - The top edge position the window is to use.
This effectively overrides any vertical alignment flags.
NOTE: the code may choose to ignore this value if it finds
that the window will not fit onto the screen unless
the top edge position is changed.
LAWN_Zoom (BOOL) - Adds a zoom gadget to the window. Clicking
on this gadget will cause the window to shrink/zoom back
to its original position. This differs from the WA_Zoom
tag behaviour. When the window zooms back to its original
position the gadgets are automatically refreshed.
Default: FALSE
LAWN_MaxPen (LONG) - The maximum rendering pen index your code
will use. Since you are -- with some restrictions -- allowed
to render into the window created you may want to avoid
silly side effects if drawing images or other colourful
textures which do not share the common user interface colours.
By default the layout code will change the maximum rendering
pen number for the window to include only the user interface
pen colours. This can, but need not disturb your own private
window rendering.
Look up graphics.library/SetMaxPen for more information.
Default: determined by looking up Screen->DrawInfo.dri_Pens
LAWN_BelowMouse (BOOL) - This instructs the layout routine to
centre the window created -- if possible -- below the
mouse pointer. This effectively ignores any left edge,
top edge or alignment settings.
Default: FALSE
LAWN_MoveToWindow (BOOL) - When the window is finally open the
user interface code will try to make sure the entire window
is visible on the screen, this may involve moving the
currently visible portion of an autoscrolling screen.
Default: TRUE
LAWN_AutoRefresh (BOOL) - Handle IDCMP_REFRESHWINDOW events
automatically.
Default: TRUE
LAWN_HelpHook (struct Hook *) - Hook code to invoke when the user
presses the "Help" key. See gtlayout.h for more information.
Default: NULL
LAWN_Parent (struct Window *) - Parent window to centre the child
window in.
Default: NULL
LAWN_BlockParent (BOOL) - Lock the parent window via LT_LockWindow()
until the child window is closed.
NOTE: requires LAWN_Parent attribute.
Default: FALSE
LAWN_SmartZoom (BOOL) - Attach a zoom gadget to the window created.
When in zoomed state, the window will be as small as possible,
showing only the window title and window gadgets:
NOTE: this tag implies LAWN_Zoom,TRUE
Default: FALSE
LAWN_Title (STRPTR) - The window title to use. Use this tag in
place of WA_Title or you will break the layout code.
Default: no title
LAWN_Bounds (struct IBox *) - Bounds to centre the window in.
Default: NULL
LAWN_ExtraWidth (LONG) - Extra width to add into the calculation
when opening the window.
Default: 0
LAWN_ExtraHeight (LONG) - Extra height to add into the calculation
when opening the window.
Default: 0
LAWN_IDCMP (ULONG) - Use this tag in place of WA_IDCMP or you
will break the object handling code.
LAWN_AlignWindow (UWORD) - Alignment information for the window, must
be a mask made from the following bit values:
ALIGNF_RIGHT - Align to screen right edge
ALIGNF_LEFT - Align to screen left edge
ALIGNF_TOP - Align to screen top edge
ALIGNF_BOTTOM - Align to screen bottom edge
Unless forbidden (such as by passing ALIGNF_RIGHT|ALIGNF_TOP)
the window will be centered horizontally and/or vertically.
LAWN_FlushLeft (BOOL) - Add no horizontal space surrounding the
objects the windows will hold. (V10)
LAWN_FlushTop (BOOL) - Add no vertical space surrounding the
objects the windows will hold. (V10)
LAWN_Show (BOOL) - Make the window visible when it is opened;
this may involve depth-arranging screens. (V10)
Default: FALSE
LAWN_NoInitialRefresh (BOOL) - If set to TRUE, adds the
gadgets, but does not draw the window imagery. You need
to draw them later by calling gtlayout.library/LT_Refresh.
Default: FALSE
LAWN_LimitWidth (UWORD) - Limit the width of the window to this
value. (V35)
LAWN_LimitHeight (UWORD) - Limit the height of the window to this
value. (V35)
LAWN_UserData (APTR) - Store this pointer with the Window information.
you can later retrieve it with the LT_GetWindowUserData()
call (V39).
RESULT
Window - Pointer to a Window structure.
SEE ALSO
gtlayout.library/LT_Refresh
gtlayout.library/LT_GetWindowUserData
intuition.library/OpenWindow
intuition.library/OpenWindowTagList
gtlayout.library/LT_CatchUpRefresh gtlayout.library/LT_CatchUpRefresh
NAME
LT_CatchUpRefresh -- Repair the display after missing the
Window refresh message (V34).
SYNOPSIS
LT_CatchUpRefresh(Handle)
A0
VOID LT_CatchUpRefresh(LayoutHandle *);
FUNCTION
In case an application missed an IDCMP_REFRESHWINDOW event
the display may be damaged and in need of repair. This can
happen if the ASL requester is attached to the window,
sharing its IDCMP with the window. Any refresh events will then
go straight to nil. Call this routine if you believe that
you missed a refresh event. The display will be repaired only
if it is in need of repair, so there is no harm in calling it
if not actually necessary.
INPUTS
Handle - Pointer to a LayoutHandle structure.
RESULT
none
SEE ALSO
gtlayout.library/LT_BeginRefresh
intuition.library/BeginRefresh
intuition.library/EndRefresh
gtlayout.library/LT_CreateHandleTagListtlayout.library/LT_CreateHandleTagList
NAME
LT_CreateHandleTagList -- Allocate auxilary data required by LT_New()
and LT_BuildA().
SYNOPSIS
Handle = LT_CreateHandleTagList(Screen,Tags);
D0 A0 A1
LayoutHandle *LT_CreateHandleTagList(struct Screen *,struct TagItem *);
Handle = LT_CreateHandleTags(Screen,...);
struct LayoutHandle *LT_CreateHandleTags(struct Screen *,...);
FUNCTION
Memory is allocated, tables are set up and data is collected
on a screen a user interface is to be opened on. This
involves calculating the screen font parameters.
INPUTS
Screen - Pointer to the screen the user interface is to
use. Passing NULL will cause the default public
screen to be used.
NOTE: if NULL is passed the default public screen
will stay locked until LT_DeleteHandle()
is called.
Tags - Tag values to control certain aspects of the
user interface created.
Valid tags include:
LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
to always keep a string gadget active if possible. Hitting
the return key will then cause the next following string
gadget to get activated, either cycling through all the
string gadgets available or stopping at the next string
gadget to have the LAST_LastGadget attribute set.
Default: TRUE
LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
events. (V13)
Default: TRUE
LAHN_UserData (APTR) - Store user specific data in the
LayoutHandle->UserData entry.
NOTE: This tag requires gtlayout.library v9 and the
corresponding entry in the LayoutHandle exists
only under gtlayout.library v9 and up. *NEVER*
write to this entry, use LT_SetAttributes()
instead.
LAHN_LocaleHook (struct Hook *) - The hook to call when
locale string IDs are to be mapped to strings. The
hook function is called with the following parameters:
String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
D0 A0 A2
LONG ID)
A1
The function is to look up the string associated with the ID
passed in and return the string.
Default: no locale hook
LAHN_TextAttr (struct TTextAttr *) - The text font to use when
creating the gadgets and objects.
Default: Screen->Font
LAHN_CloningPermitted (BOOL) - If a window will not fit onto the
screen the user interface is intended for, the layout engine
will scale the interface data down while stepping down in
font size. If all this fails, the engine will open a custom
screen for the window; this process is called "cloning".
The LAHN_CloningPermitted tag controls whether the engine will
actually try to open the custom screen or just return NULL
when LT_Build fails.
Default: TRUE
LAHN_EditHook (struct Hook *) - You can specify a default string
gadget editing hook to be used for all following string
gadgets. Your hook should obey the same rules that apply
to hooks passed via GTST_EditHook/GTIN_EditHook.
Default: NULL
LAHN_ExactClone (BOOL) - This tag works in conjunction with the
LAHN_CloningPermitted tag. By default the layout engine will
try to replicate only the basic characteristics of the
screen the window was intended to open on. This may result
in a screen which uses less colours than the original
screen. You can force the engine to make an almost exact
clone of the original screen by passing the LAHN_ExactClone
tag with a value of TRUE.
Default: FALSE
LAHN_MenuGlyphs (BOOL) - This tag will make the layout engine
fill in the AmigaGlyph and CheckGlyph entries of the
LayoutHandle if running under Kickstart 3.0 or higher.
The corresponding images will be scaled to fit the actual
screen aspect ratio values and can later be used for
menu layout.
Default: FALSE
LAHN_Parent (struct Window *) - You can pass a pointer to the
parent window of the window you intend to open using
the user interface layout engine. The new window will
open inside the boundaries of the parent window. If the
size does not fit, it will be opened centered over the
parent window.
Default: NULL
LAHN_BlockParent (BOOL) - This tag works in conjunction with the
LAHN_Parent tag. If in effect, will block the parent window
via LT_LockWindow until the new window is closed, after
which the parent window is unlocked again.
Default: FALSE
LAHN_SimpleClone (BOOL) - This tag works in conjunction with the
LAHN_CloningPermitted tag. It will make the layout engine
forget most information about the original screen the
user interface was intended for. In short, it will open a
simple default screen for the interface.
Default: FALSE
LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
of with LT_DeleteHandle() all variables maintained by the
input handling code will be flushed. For example, if you
would use the LA_STRPTR tag for STRING_KIND objects the
last string gadget contents would be copied into the buffer
pointed to by LA_STRPTR. If you do not want to use this
feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
Default: TRUE
LAHN_NoKeys (BOOL) - Use TRUE to tell the library not to pick
keyboard shortcuts all on its own. This works like calling
LT_New() for all objects with "LA_NoKey,TRUE,". (V26)
LAHN_PubScreen (struct Screen *) - Pointer to public screen
window is to open on. Must be locked and open until you call
LT_Built().
LAHN_PubScreenName (STRPTR) - Name of public screen to open window
on. The library will try to lock the named screen as soon as
you call LT_CreateHandle.
LAHN_PubScreenFallBack (BOOL) - If the named public screen cannot
be found and you ask for it, the library will lock the default
public screen (default: TRUE).
RESULT
Handle - Pointer to a LayoutHandle structure.
gtlayout.library/LT_DeleteHandle gtlayout.library/LT_DeleteHandle
NAME
LT_DeleteHandle -- Release storage space allocated by
LT_CreateHandleTagList, closing windows,
removing gadgets, etc.
SYNOPSIS
LT_DeleteHandle(Handle);
A0
VOID LT_DeleteHandle(LayoutHandle *);
FUNCTION
Windows and gadgets created by LT_CreateHandleTagList()
are removed, any associated memory is deallocated.
INPUTS
Handle - Pointer to a LayoutHandle structure created
by LT_CreateHandleTaglist(). Passing NULL is
harmless.
RESULT
none
SEE ALSO
gtlayout.library/CreateHandleTagList
gtlayout.library/LT_DeleteWindowLock gtlayout.library/LT_DeleteWindowLock
NAME
LT_DeleteWindowLock -- Remove all locks from a window
SYNOPSIS
LT_DeleteWindowLock(Window);
A0
VOID LT_DeleteWindowLock(struct Window *);
FUNCTION
Before closing a locked window you should call this routine
which will remove all outstanding locks from it.
INPUTS
Window - Pointer to window structure; passing NULL is
harmless.
RESULT
none
gtlayout.library/LT_DisposeMenu gtlayout.library/LT_DisposeMenu
NAME
LT_DisposeMenu -- Release storage space allocated by
LT_NewMenuTemplate or LT_NewMenuTagList (V11)
SYNOPSIS
LT_DisposeMenu(Menu)
A0
VOID LT_DisposeMenu(struct Menu *);
FUNCTION
Menus and MenuItems allocated by LT_NewMenuTemplate or
LT_NewMenuTagList are deallocated.
INPUTS
Menu - Pointer to Menu structure as returned by
LT_NewMenuTemplate or LT_NewMenuTagList. Passing
NULL is harmless.
RESULT
none
SEE ALSO
gtlayout.library/LT_NewMenuTagList
gtlayout.library/LT_NewMenuTemplate
gtlayout.library/LT_EndGroup gtlayout.library/LT_EndGroup
NAME
LT_EndGroup -- end a group declaration.
SYNOPSIS
LT_EndGroup(Handle);
A0
VOID LT_EndGroup(LayoutHandle *);
FUNCTION
This is just a short form of
LT_New(Handle,
LA_Type, END_KIND,
TAG_DONE);
It helps to save (some) space.
INPUTS
Handle - Pointer to LayoutHandle.
RESULT
none
SEE ALSO
gtlayout.library/LT_New
gtlayout.library/LT_EndRefresh gtlayout.library/LT_EndRefresh
NAME
LT_EndRefresh -- Optimized window refreshing
SYNOPSIS
LT_EndRefresh(Handle)
A0
VOID LT_EndRefresh(LayoutHandle *);
FUNCTION
If you wish to handle window refreshing all on your own, you
might want to use the LT_BeginRefresh...LT_EndRefresh pair
in your program. By default the user interface layout engine
will automatically intercept IDCMP_REFRESHWINDOW events and
react to them accordingly.
INPUTS
Handle - Pointer to a LayoutHandle structure.
RESULT
none
SEE ALSO
gtlayout.library/LT_BeginRefresh
intuition.library/BeginRefresh
intuition.library/EndRefresh
gtlayout.library/LT_Exit gtlayout.library/LT_Exit
NAME
LT_Exit -- Clean up user interface allocations
SYNOPSIS
LT_Exit();
VOID LT_Exit(VOID);
FUNCTION
When you are finished with user interface creation and
do not not need the code any more you should call this
routine. It will free all the memory allocated by
LT_Init(), close libraries, etc.
INPUTS
none
RESULT
none
NOTES
This function is not present in the shared library, only
in the link library. You need not and cannot invoke it in
the shared library.
SEE ALSO
gtlayout.library/LT_Init
gtlayout.library/LT_FindMenuCommand gtlayout.library/LT_FindMenuCommand
NAME
LT_FindMenuCommand -- Get the menu/submenu item associated
with a rawkey event (V11)
SYNOPSIS
Item = LT_FindMenuCommand(Menu,Code,Qualifier,Gadget)
D0 A0 D0 D0 A1
struct MenuItem *LT_FindMenuCommand(struct Menu *,
UWORD,ULONG,struct Gadget *);
FUNCTION
With the IntuiMessage data copied from a type IDCMP_RAWKEY message
tries to find the MenuItem the event referred to.
INPUTS
Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
Code - Value copied from IntuiMessage->Code
Qualifier - Value copied from IntuiMessage->Qualifier
Gadget - Value copied from IntuiMessage->IAddress
RESULT
Item - Pointer to the struct MenuItem * in question or NULL
if none could be found
SEE ALSO
gtlayout.library/LT_NewMenuTagList
gtlayout.library/LT_GetAttributesA gtlayout.library/LT_GetAttributesA
NAME
LT_GetAttributesA -- Inquire information on a gadget.
SYNOPSIS
Value = LT_GetAttributesA(Handle,ID,Tags);
D0 A0 D0 A1
LONG LT_GetAttributesA(LayoutHandle *,LONG ID,struct TagItem *);
Value = LT_GetAttributes(Handle,ID,...);
LONG LT_GetAttributes(LayoutHandle *,LONG ID,...);
FUNCTION
All objects created by the user interface layout code posess
certain unique properties. The LT_GetAttributes() function will
will inquire this information and return it. The implementation
differs from gadtools.library/GT_GetGadgetAttrs in that you
can inquire only a small subset of the object properties possible
via the taglist passed in.
INPUTS
Handle - Pointer to LayoutHandle structure.
ID - ID number of the object to inquire information about. This
is the same value you passed via LA_ID to LT_New() when
you created this object.
Tags - TagItem list to receive information about the object
in question.
LA_Left (LONG *) - Left edge of object.
LA_Top (LONG *) - Top edge of object.
LA_Width (LONG *) - Width of object.
LA_Height (LONG *) - Height of object.
LA_Chars (LONG *) - Width of object measured in character
widths. (V9)
LA_Lines (LONG *) - Height of object measured in character
heights. (V9)
LA_LabelLeft (LONG *) - Left edge of label text. (V9)
LA_LabelTop (LONG *) - Top edge of label text. (V9)
LABO_Object (Object *) - Returns a pointer to the BOOPSI object
the BOOPSI_KIND object is based upon. (V10)
NOTE: Don't unlink the object or dispose of it or
terrible things are bound to happen.
LAST_CursorPosition (LONG *) - Current position of the cursor
in STRING_KIND and FRACTION_KIND objects. (V
RESULT
The result depends on the object type:
VERTICAL_KIND:
HORIZONTAL_KIND:
active page
SCROLLER_KIND:
current GTSC_Top value
TAPEDECK_KIND:
current LATD_Pressed value
LEVEL_KIND:
current LAVL_Level state
CHECKBOX_KIND:
current GTCB_Checked state
LISTVIEW_KIND:
current GTLV_Selected state
MX_KIND:
current GTMX_Active state
CYCLE_KIND:
current GTCY_Active state
POPUP_KIND:
current LAPU_Active state
TAB_KIND:
current LATB_Active state
PALETTE_KIND:
current GTPA_Color state
SLIDER_KIND:
current GTSL_Level state
GAUGE_KIND:
current LAGA_Percent state
STRING_KIND:
pointer to current string
PASSWORD_KIND:
pointer to current string
INTEGER_KIND:
number currently entered
BOOPSI_KIND:
whatever the object thinks is its
current value
gtlayout.library/LT_GetCode gtlayout.library/LT_GetCode
NAME
LT_GetCode -- Easy raw key event to ANSI conversion.
SYNOPSIS
Key = LT_GetCode(Qualifier,Class,Code,Gadget);
D0 D0 D1 D2 A0
LONG LT_GetCode(ULONG,ULONG,UWORD,struct Gadget *);
FUNCTION
The user interface layout engine can convert IDCMP_RAWKEY
events into ANSI codes. Pass in the data you copied from
the IntuiMessage here.
INPUTS
Qualifier - Copied from IntuiMessage->Qualifier
Class - Copied from IntuiMessage->Class
Code - Copied from IntuiMessage->Code
Gadget - Copied from IntuiMessage->IAddress
RESULT
Key - ANSI code generated from the input data
or -1 if no such code was to be generated.
gtlayout.library/LT_GetIMsg gtlayout.library/LT_GetIMsg
NAME
LT_GetIMsg -- Retrieve the next pending IntuiMessage
from the window associated with a
LayoutHandle.
SYNOPSIS
IntuiMessage = LT_GetIMsg(Handle);
D0 A0
struct IntuiMessage *LT_GetIMsg(LayoutHandle *);
FUNCTION
This routine will handle most of the input loop for
you. Just pass the pointer to the layout handle in,
check if the result code is non-null, copy the data
you need and reply the message via LT_ReplyIMsg().
You will still need to wait for new input, as LT_GetIMsg
will poll the MsgPort of the window.
LT_GetIMsg() will try its best to distinguish between
different LayoutHandles sharing the same Window->UserPort.
If it finds that the window the message was sent to is
using a different LayoutHandle, it will switch to using
this handle (V13).
INPUTS
Handle - Pointer to LayoutHandle structure
RESULT
IntuiMessage - Pointer to IntuiMessage structure
NOTES
You *must not* make any assumptions about the contents
of the IntuiMessage structure except for the following
entries:
Class
Code
Qualifier
IAddress
When finished, you must dispose the IntuiMessage via
LT_ReplyIMsg or memory will be lost which can never
be reclaimed.
DO NOT CALL LT_HandleInput() ON THE DATA YOU RECEIVE
FROM LT_GetIMsg() AS LT_GetIMsg() ALREADY DOES ALL THE
MAGIC LT_HandleInput() OTHERWISE WOULD NEED TO DO!
IF YOU STILL DO CALL LT_HandleInput() ON THE DATA YOU
WILL RECEIVE `GHOST' EVENTS.
SEE ALSO
gtlayout.library/LT_ReplyIMsg
gtlayout.library/LT_GetMenuItem gtlayout.library/LT_GetMenuItem
NAME
LT_GetMenuItem -- Get the menu/submenu item associated with an ID (V11)
SYNOPSIS
Item = LT_GetMenuItem(Menu,ID)
D0 A0 D0
struct MenuItem *LT_GetMenuItem(struct Menu *,ULONG);
FUNCTION
This routine scans through all menu items associated with the
menu and returns a pointer to the item associated with the
given ID value.
INPUTS
Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
ID - Unique ID of the item to find.
RESULT
Item - Pointer to the struct MenuItem * in question or NULL
if none could be found
SEE ALSO
gtlayout.library/LT_NewMenuTagList
gtlayout.library/LT_GetWindowUserData gtlayout.library/LT_GetWindowUserData
NAME
LT_GetWindowUserData -- Obtain user data information associated
with a Window created by gtlayout.library/LT_Build (V39).
SYNOPSIS
Data = LT_GetWindowUserData(Window,DefaultValue);
D0 A0 A1
APTR LT_GetWindowUserData(struct Window *,APTR);
FUNCTION
You can tell the build process to store user data with the Window
it creates. This can be used as a replacement for the Window->UserData
pointer information which gtlayout.library uses for itself. If the
Window you pass to this routine was created by gtlayout.library/LT_Build
you will receive the user data pointer you passed in, otherwise the
given default value will be returned.
INPUTS
Window - Pointer to a Window created by gtlayout.library/LT_Build
RESULT
Data - The user data pointer you provided for gtlayout.library/LT_Build
with the LAWN_UserData tag or the default value if no such pointer
was provided or this Window was not created by
gtlayout.library/LT_Build.
DefaultValue - If the window was not created by gtlayout.library/LT_Build
this is the value you will receive as the function result.
SEE ALSO
gtlayout.library/LT_Build
gtlayout.library/LT_HandleInput gtlayout.library/LT_HandleInput
NAME
LT_HandleInput -- Filter IntuiMessage data.
SYNOPSIS
LT_HandleInput(Handle,Qualifier,Class,Code,Gadget);
A0 D0 A1 A2 A3
VOID LT_HandleInput(LayoutHandle *,ULONG,ULONG *,
UWORD *,struct Gadget **);
FUNCTION
In order to keep track of user interface actions, such as
keys getting pressed, sliders getting moved, etc. your
code is to call LT_HandleInput() with data copied from the
IntuiMessage it has just received and replied.
INPUTS
Handle - Pointer to a LayoutHandle structure.
Qualifier - The Qualifier value copied from the
IntuiMessage structure.
Class - Pointer to the ULONG variable which holds the
value copied from the Class entry of the
IntuiMessage structure.
Code - Pointer to the UWORD variable which holds the
value copied from the Code entry of the
IntuiMessage structure.
Gadget - Pointer to the Gadget value copied from the
IAddress entry of the IntuiMessage structure.
RESULT
none
EXAMPLE
struct IntuiMessage *IntuiMessage;
ULONG Qualifier,Class;
UWORD Code;
struct Gadget *Gadget;
for(;;)
{
WaitPort(Window->UserPort);
while(IntuiMessage = GT_GetIMsg(Window->UserPort))
{
Class = IntuiMessage->Class;
Code = IntuiMessage->Code;
Qualifier = IntuiMessage->Qualifier;
Gadget = IntuiMessage->Gadget;
GT_ReplyIMsg(IntuiMessage);
LT_HandleInput(Handle,Qualifier,&Class,&Code,&Gadget);
}
}
NOTES
For BOOPSI_KIND objects keystroke activation may lead to
unexpected results. Your application will hear a IDCMP_GADGETUP
event, the IntuiMessage->Code value will hold the ANSI key
code of the key the user pressed.
Do not call this routine before you have actually
replied the IntuiMessage received or weird things
may happen. This is not a suggestion, it's a threat.
gtlayout.library/LT_Init gtlayout.library/LT_Init
NAME
LT_Init -- Initialize user interface code.
SYNOPSIS
LT_Init();
VOID LT_Init(VOID);
FUNCTION
You need to initialize the user interface code only once,
so it can set up its internals, open libraries, etc.
The code has to be initialized before any user interface
creation can take place.
NOTES
This function is not present in the shared library, only
in the link library. You need not and cannot invoke it in
the shared library.
SEE ALSO
gtlayout.library/LT_Exit
gtlayout.library/LT_LabelChars gtlayout.library/LT_LabelChars
NAME
LT_LabelChars -- Calculate the width of a a string
according to the user interface font
associated with a LayoutHandle.
SYNOPSIS
Length = LT_LabelChars(Handle,Label);
D0 A0 A1
LONG LT_LabelChars(struct LayoutHandle *,STRPTR);
FUNCTION
Calculates the width of a string according to the user
interface font used. The width is then converted to a number
of characters suitable for using with the LA_Chars tag
item when calling LT_New().
You can pass multi-line label texts to this routine,
it will calculate the maximum length of the single
lines. (V12)
INPUTS
Handle - Pointer to LayoutHandle structure.
Label - Pointer to string.
RESULT
Length - Number of characters that are considered
equivalent to the string length in pixels.
gtlayout.library/LT_LabelWidth gtlayout.library/LT_LabelWidth
NAME
LT_LabelWidth -- Calculate the width of a string according
to the user interface font used.
SYNOPSIS
Width = LT_LabelWidth(Handle,Label);
D0 A0 A1
LONG LT_LabelWidth(LayoutHandle *,STRPTR);
FUNCTION
This routine calculates the width of strings in
terms of pixels according to the user interface
font associated with the LayoutHandle.
You can pass multi-line label texts to this routine,
it will calculate the maximum length of the single
lines. (V12)
INPUTS
Handle - Pointer to LayoutHandle structure.
RESULT
Width - Width of the text string in pixels.
gtlayout.library/LT_LayoutMenusA gtlayout.library/LT_LayoutMenusA
NAME
LT_LayoutMenusA -- Create a menu according to a template.
SYNOPSIS
Menu = LT_LayoutMenusA(Handle,Template,Tags);
D0 A0 A1 A2
struct Menu *LT_LayoutMenusA(LayoutHandle *,struct NewMenu *,
struct TagItem *);
Menu = LT_LayoutMenus(Handle,Template,...);
struct Menu *LT_LayoutMenus(LayoutHandle *,struct NewMenu *,...);
FUNCTION
Unlike the corresponding routines in gadtools.library
LT_LayoutMenusA() will both create and layout a menu.
Also included is locale support.
INPUTS
Handle - Pointer to LayoutHandle structure.
Template - Address of a ready-to-use NewMenu table to
create the menu from.
Tags - Tagitem list to control menu attributes
Tags:
LAMN_FirstLabel (LONG) - Locale ID of the first string to
use as a menu title/item/subitem label. This tag
works in conjunction with LA_LastLabel.
LAMN_LastLabel (LONG) - Locale ID of the last string to
use as a menu title/item/subitem label. This tag
works in conjunction with LA_FirstLabel. The code
will loop through FirstLabel..LastLabel and assign
the corresponding locale text for each ID to the
NewMenu.nm_Label entries. Labels which are already
initialized with NM_BARLABEL are skipped.
LAMN_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the menu labels. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
RESULT
Menu - Pointer to a Menu structure. You can free this
using gadtools.library/FreeMenus().
gtlayout.library/LT_LevelWidth gtlayout.library/LT_LevelWidth
NAME
LT_LevelWidth -- Determine the maximum width of a SLIDER_KIND
level string.
SYNOPSIS
Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
D0 A0 A1 A2 D0 D1 A3
MaxLen,FullCheck);
A5 D2
LONG LT_LevelWidth(LayoutHandle *,STRPTR,
LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
LONG *,BOOL);
FUNCTION
In order to make room for the level text displayed by a
SLIDER_KIND object one needs to know how much space the
longest level string will occupy. Otherwise, the level
text may overwrite the gadget label text or the slider
container. This routine will rattle through all possible
slider settings (as given via the Min and the Max
level values) and determine the longest label string
according to the font used.
INPUTS
Handle - Pointer to a LayoutHandle structure, as returned by
a call to LT_CreateHandleTags().
FormatString - The sprintf() style formatting string to be used
to format the slider level settings into text.
This is the same string you would pass in via
the GTSL_LevelFormat tag when creating the
slider object.
Default: "%lD" for systems which have locale.library
installed, "%ld" otherwise.
DispFunc - A pointer to the function to filter the slider level
values. The result of this function will then be
used to format a string into the slider level text.
This is the same parameter you would pass in via
the GTSL_DispFunc tag when creating the slider
object.
NOTE: the routine will be called with a NULL Gadget
parameter, make sure your code will handle
this nicely.
Default: no display function
Min - The smallest value the slider can be set to. This is
same value you would pass in via GTSL_Min when creating
the slider object.
Max - The largest value the slider can be set to. This is
same value you would pass in via GTSL_Max when creating
the slider object.
MaxWidth - Pointer to a place to store the width of the
longest level string in pixels. If you pass
in NULL instead of the address of a variable
no harm will be done.
MaxLen - Pointer to a place to store the length of the
longest level string in characters. If you pass
in NULL instead of the address of a variable
no harm will be done.
FullCheck - TRUE will cause the code to rattle through all
possible slider settings, starting from the
minimum value, ending at the maximum value.
While this may be a good idea for a display
function to map slider levels to text strings
of varying length it might be a problem when
it comes to display a range of numbers from
1 to 40,000: the code will loop through
40,000 iterations trying to find the longest
string.
FALSE will cause the code to calculate the
longest level string based only on the
minimum and the maximum value to check.
While this is certainly a good a idea when
it comes to display a range of numbers from
1 to 40,000 as only two values will be
checked the code may fail to produce
accurate results for sliders using display
functions mapping slider levels to strings.
RESULT
Index - The slider level which gives the longest
level string.
NOTES
Some compilers have trouble passing parameters in A5. In such
a case it is recommended to use gtlayout.library/LT_NewLevelWidth
instead.
SEE ALSO
gtlayout.library/LT_NewLevelWidth
gtlayout.library/LT_LockWindow gtlayout.library/LT_LockWindow
NAME
LT_LockWindow -- Block user access to a window.
SYNOPSIS
LT_LockWindow(Window);
A0
VOID LT_LockWindow(struct Window *);
FUNCTION
The window will get a wait mouse pointer attached and a blank
Requester, preventing any user gadgets from getting used. The
window minimum and maximum sizes are set to the current window
size so the user will be unable to resize the window or click
on the zoom gadget.
This routine nests, multiple calls to LT_LockWindow() using the
same window will increment a usage counter, so exactly the
same number of calls to LT_UnlockWindow() will be required to
unlock the window.
INPUTS
Window - Pointer to window structure; passign NULL is harmless.
RESULT
none
NOTES
Do not close the window you have locked unless all the
outstanding locks are freed or memory will be lost which
can never be reclaimed. Before you close the window,
call gtlayout.library/LT_DeleteWindowLock.
SEE ALSO
gtlayout.library/LT_DeleteWindowLock
gtlayout.library/LT_MenuControlTagList gtlayout.library/LT_MenuControlTagList
NAME
LT_MenuControlTagList -- Manipulate menus, menu/submenu items (V11)
SYNOPSIS
LT_MenuControlTagList(Window,Menu,Tags)
A0 A1 A2
VOID LT_MenuControlTagList(struct Window *,struct Menu *,struct TagItem *);
VOID LT_MenuControlTags(struct Window *,struct Menu *,...);
FUNCTION
This routine provides a rather efficient way to set and to clear,
to enable and to disable a number of menus, menu/submenu items
all at once.
In v18 this routine was modified to disconnect a menu strip
from a window if it is about to change checkmark states. In
earlier releases or if a single menu is attached to several
windows it is recommended that you disconnect the menu from
the windows it is attached to before you call this routine.
As of v18 this routine is smart enough to handle menu
mutual exclusion.
INPUTS
Window - Pointer to Window this menu is attached to. Starting with
gtlayout.library v16 this parameter may be NULL.
Menu - Pointer to Menu structure as returned by LT_NewMenuTagList.
Tags - Pointer to a list of tagitem values, as found
in gtlayout.h
Tags:
LAMN_ID (ULONG) - Unique ID of menu/menu item/submenu item to
manipulate.
LAMN_Checked (BOOL) - Set the checkmark state of the
menu/submenu item.
LAMN_Disabled (BOOL) - Set the availability state of the
menu/menu item/submenu item.
LAMN_FullMenuNum (UWORD) - Intuition menu number of
menu/submenu item to manipulate. You would pass the
result of the FULLMENUNUM() macro here for the
item in question. (V30)
RESULT
none
EXAMPLE
The following tagitem list will clear the checkmark and
disable the menu item associated with ID 5 and set the
checkmark for the item associated with ID 6:
LAMN_ID, 5,
LAMN_Checked, FALSE,
LAMN_Disabled, TRUE,
LAMN_ID, 6,
LAMN_Checked, TRUE,
TAG_DONE
BUGS
In library versions up to and including v17.2 this routine
is broken. It won't do any harm, it just doesn't do what you
want it to do.
Up to and including V42.1 the library could fail to find the
correct menu items corresponding to the LAMN_ID given. This
has been fixed in V43.1.
Up to and including V43.1 trying to change the attributes
of an item with LAMN_ID whose ID number could not be found
could lead to a crash. This has been fixed in V43.2.
SEE ALSO
gtlayout.library/LT_NewMenuTagList
gtlayout.library/LT_NewA gtlayout.library/LT_NewA
NAME
LT_NewA -- Add a new object to the user interface tree.
SYNOPSIS
LT_NewA(Handle,Tags);
A0 A1
VOID LT_NewA(LayoutHandle *,struct TagItem *);
LT_New(Handle,...);
VOID LT_New(LayoutHandle *,...);
FUNCTION
LT_NewA() is the routine you use to build the user interface,
you give layout directions, design groups, etc. and finally
call LT_BuildA() to turn these specifications into a window.
INPUTS
Handle - Pointer to LayoutHandle structure.
This routine will accept almost all create-time tag items
gadtools.library/CreateGadget will handle. In addition to
this there are a bunch of extra gadget objects and extra
tag items supported:
All object types:
LA_Type (LONG) - Type of the object to create, must be
one of the following:
TEXT_KIND
VERTICAL_KIND
HORIZONTAL_KIND
END_KIND
FRAME_KIND
BOX_KIND
SLIDER_KIND
LISTVIEW_KIND
INTEGER_KIND
STRING_KIND
PASSWORD_KIND
PALETTE_KIND
BUTTON_KIND
CHECKBOX_KIND
NUMBER_KIND
GAUGE_KIND
CYCLE_KIND
POPUP_KIND
TAB_KIND
MX_KIND
XBAR_KIND
YBAR_KIND
TAPEDECK_KIND
LEVEL_KIND
BOOPSI_KIND
BLANK_KIND (V36)
FRACTION_KIND (V38)
IMAGE_KIND (V41)
LA_LabelText (STRPTR) - The object label text to use.
LA_LabelID (LONG) - The locale text ID of the string to
use as the object label text.
NOTE: LT_NewA() will fail if you forget
to select a hook with LAHN_LocaleHook
at LT_CreateHandleTagList.
LA_ID (LONG) - The gadget ID to use for this object.
NOTE: User ID values *MUST* be greater than 0,
negative values are reserved for internal
use.
LA_Chars (LONG) - The width of this object measured in
characters. If each character of the user interface
font is 8 pixels wide an object with LA_Chars set to
10 will usually be 80 pixels wide.
LA_LabelChars (LONG) - This forces the internal gadget
label width the layout engine calculates during the
layout pass to a specific value. Note: this does
not work well with all objects. (V9)
LA_LabelPlace (LONG) - Where to place the gadget label.
Not all objects will support all label positions:
PLACE_LEFT - Place label text left of object
PLACE_RIGHT - Place label text right of object
PLACE_ABOVE - Place label text above object
PLACE_IN - Place label text in object
PLACE_BELOW - Place label text below object
LA_ExtraSpace (BOOL) - Add extra vertical/horizontal
space before this object.
Default: FALSE
LA_ExtraFat (BOOL) - Make this object a bit larger
than its usual size.
Default: FALSE
LA_NoKey (BOOL) - Don't let the user interface choose
a keyboard shortcut for this object.
Default: FALSE
LA_HighLabel (BOOL) - Use highlight pen when rendering
the gadget label text.
Default: FALSE
LA_BYTE (BYTE *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_UBYTE (UBYTE *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_WORD (WORD *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_UWORD (UWORD *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_BOOL (BOOL *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_LONG (LONG *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_ULONG (ULONG *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_STRPTR (STRPTR) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
LA_FRACTION (FRACTION *) - Pointer to the variable that holds
the "current value" of the object. The layout engine
will retrieve this value initially during the creation
of the object and maintain it during its lifespan.
This means you do not need to worry about checking
the state of the object, the user interface layout
engine will do it for you.
BLANK_KIND (transparent placeholder):
(requires gtlayout.library V36 or higher)
No tags are defined for this type of object.
BOOPSI_KIND:
(requires gtlayout.library V10 or higher)
LABO_TagCurrent (Tag) - The Tag ID that represents the
current object value. For PROPGCLASS this would be
PGA_Top.
LABO_TagTextAttr (Tag) - The Tag ID that represents the
TextAttr value the object expects. For gadgets this
would be GA_TextAttr.
LABO_TagDrawInfo (Tag) - The Tag ID that represents the
DrawInfo value the object expects.
LABO_TagLink (Tag) - The Tag ID that represents a pointer
to a different object the object expects. For the
colorwheel.gadget this would be WHEEL_GradientSlider.
LABO_TagScreen (Tag) - The Tag ID that represents the
screen the object expects. For the colorwheel.gadget
this would be WHEEL_Screen.
LABO_Link (LONG) - The ID of the object this object should
be linked to. This will be resolved later when gadgets
are created.
NOTE: Forward references are not resolved, only
backward references are allowed. This means that
if you wish to link object A to object B,
object A must be created before object B
is created.
LABO_ClassInstance (Class *) - This is the first parameter
you would pass to NewObjectA().
NOTE: Only classes derived from gadgetclass and
gadgetclass itself may be used.
LABO_ClassName (STRPTR) - This is the second parameter you would
pass to NewObject().
NOTE: Only classes derived from gadgetclass and
gadgetclass itself may be used.
LABO_ClassLibraryName (STRPTR) - This tag is particularly useful
for gadget class implementations wrapped into libraries, such as
colorwheel.gadget. When opened, they make the classes they
represent publicly available so subsequent calls to
NewObject(NULL,<Classname>,...) can be made. The
LABO_ClassLibraryName tag will cause gtlayout.library to open
the class library before any calls to NewObject() are made.
NOTE: Only classes derived from gadgetclass and
gadgetclass itself may be used.
The LABO_ClassLibraryName tag requires that you
specify the class name with the LABO_ClassName. It is
not enough to just use the LABO_ClassLibraryName tag.
LABO_ExactWidth (WORD) - This is the exact width of the object to
use. This effectively overrides whatever you specified using
the LA_Chars tag and keeps gtlayout.library from shrinking and
expanding the object as needed.
LABO_ExactHeight (WORD) - This is the exact height of the object to
use. This effectively overrides whatever you specified using
the LA_Lines tag and keeps gtlayout.library from shrinking and
expanding the object as needed.
LABO_RelFontHeight (WORD) - This tag affects the height of the
object; when specified, it is derived from the user interface
font height plus the value given with LABO_RelFontHeight.
LABO_FullWidth (BOOL) - Use this tag if you wish the object to
cover the entire width of the group it resides within.
LABO_FullHeight (BOOL) - Use this tag if you wish the object to
cover the entire height of the group it resides within.
LABO_ActivateHook (struct Hook *) - Hook to invoke when the
layout engine decides that this particular object should
be activated. The hook is called with the following
parameters:
Success = ActivateFunc(struct Hook *Hook,LayoutHandle *Handle,
D0 A0 A2
Object *object)
A1
The object pointer actually refers to the instance of the
BOOPSI object created. Return FALSE if your object could not
be activated, TRUE if it worked. If you return TRUE, no special
keyboard event will be generated. (V13)
NOTE: All tags passed to LT_New() for BOOPSI_KIND objects are
passed through to NewObjectA() later. The library makes
a copy of the tag item list, so all data valid in the
scope when LT_New() is called must also be valid later
when LT_Build() is invoked.
The gadget label is *NOT* passed through to the object,
it effectively receives the label a plain gadtools object
would receive, similar to what happens to FRAME_KIND
objects and the like.
BOX_KIND (multiline text display):
LABX_Chars (LONG) - The width of this object in
characters. The layout routine will try to make
sure that the given number of characters will
fit into a single line of text in this box.
This may be a problem with proportional spaced
fonts.
Default: 10
LABX_Labels (STRPTR *) - The label texts to display
on the right hand side of the box. Terminate
this array with NULL.
LABX_Lines (STRPTR *) - The text to display in the
box. Terminate this array with NULL.
LABX_Rows (LONG) - The height of this object in
characters.
LABX_AlignText (LONG) - Controls how text is aligned
in box lines:
ALIGNTEXT_LEFT - Align text to the left edge
ALIGNTEXT_CENTERED - Centre the text
ALIGNTEXT_RIGHT - Align text to the right edge
ALIGNTEXT_PAD - Pad text lines
Default: ALIGNTEXT_LEFT
LABX_DrawBox (BOOL) - Draw a recessed bevel box
around the text box.
Default: FALSE
LABX_FirstLabel (LONG) - Locale string ID of the first
text to use as a box label. Works in conjunction
with LABX_LastLabel.
LABX_LastLabel (LONG) - Locale string ID of the last
text to use as a box label. Works in conjunction
with LABX_FirstLabel. When building the interface the
code will loop from FirstLabel..LastLabel, look
up the corresponding locale strings and use the
data to make up the label text to appear at the
right hand side of the box.
LABX_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the box labels. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
LABX_ReserveSpace (BOOL) - Allocate extra memory to hold
the contents of the lines displayed. This avoids nasty
side-effects when refreshing this object.
Default: FALSE
LABX_FirstLine (LONG) - Locale string ID of the first
text to print inside the box. Works in conjunction
with LABX_LastLine. (V26)
LABX_LastLine (LONG) - Locale string ID of the last
text to print inside the box. Works in conjunction
with LABX_FirstLine. (V26)
LABX_LineTable (LONG *) - Pointer to an array of IDs
to use for building the box contents lines. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1. (V28)
LABX_Line (STRPTR) - Line to display in the box, may
contain '\n' line break characters, the layout engine
will chop the single line into single consecutive lines
following the '\n' chars. (V31)
LABX_LineID (LONG) - Locale ID of line text to display in the
box, may contain '\n' line break characters, the layout
engine will chop the single line into single consecutive lines
following the '\n' chars. (V31)
LABX_TextPen (WORD) - Box text colour to use. (V40)
LABX_BackPen (WORD) - Box text background colour to use. (V40)
LABX_Spacing (UWORD) - Request that additional pixels should
separate lines of text. (V41)
Default: 0
BUTTON_KIND:
LA_Label (STRPTR)
LA_LabelID (LONG) - These two define the button label, i.e.
the text that is printed within the button box. Optionally,
this text may include newline characters ("\n") which will
cause the button text to be broken into several lines.
This particular feature requires gtlayout.library v12 or
higher. Single line label have always been supported.
LABT_ReturnKey (BOOL) - Let the user operate this
button by pressing the return key, making it the
so-called default button, or default choice. The
button select box will appear slightly bolder than
normal buttons are.
NOTE: there can be only one single button per
window to sport this feature.
Default: FALSE
LABT_EscKey (BOOL) - Let the user operate this
button by pressing the Escape key.
NOTE: there can be only one single button per
window to use this feature.
Default: FALSE
LABT_ExtraFat (BOOL) - Make this button a bit
larger than usual.
Default: FALSE
LABT_Lines (STRPTR *) - Use the given string array
to create a multiline gadget label. Terminate the
array with a NULL. (V12)
LABT_FirstLine (LONG) - Locale ID of first label line. (V12)
LABT_LastLine (LONG) - Locale ID of last label line. (V12)
LABT_DefaultCorrection (BOOL) - Make the button slightly
wider and taller so its size matches the default
button. (V21)
LABT_Smaller (BOOL) - Make this button a little smaller
than usual. (V21)
CYCLE_KIND:
LACY_FirstLabel (LONG) - Locale string ID of the first
text to use as a label. Works in conjunction
with LACY_LastLabel.
LACY_LastLabel (LONG) - Locale string ID of the last
text to use as a label. Works in conjunction
with LACY_FirstLabel. When building the interface the
code will loop from FirstLabel..LastLabel, look
up the corresponding locale strings and use the
data to make up the label text.
LACY_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the cycle labels. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
LACY_TabKey (BOOL) - Connect this object to the tabulator
key. Press [Tab] to cycle to the next entry, [Shift][Tab]
to cycle to the previous entry. (V9)
NOTE: there can be only one single button per
window to use this feature.
Default: FALSE
LACY_AutoPageID (LONG) - ID of paged GROUP_KIND object
which will be set to the gadget's current setting.
If this tag is set, you will hear no events from this
object any more. (V7)
NOTE: Listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
FRACTION_KIND:
(requires gtlayout.library V38 or higher)
This is a special kind of STRING_KIND which comes with a
special input filter. It will allow only for floating point
numbers to be entered, i.e. numbers (`0'-`9') and one
decimal point (`.' or whatever your current locale uses
as the decimal point character). What you will receive as
user input text will be in the following format:
(0|#[0-9]).(0|#[0-9])
Or in other words, text like this will be returned:
0.0
7.0
0.9
146654.0
NOTE: While this object type did exist in earlier library
versions support for it was removed in V33. It was
eventually reintroduced with the functionality described
above in V38.
LAFR_IncrementerHook (struct Hook *) - Hook to invoke when the
incrementer arrows are used. The hook function will receive
three parameters and has to return a result code:
a0 - (struct Hook *) Pointer to this hook
a2 - (STRPTR) Current value of this object
a1 - (LONG) Either INCREMENTERMSG_Decrement or
INCREMENTERMSG_Increment
If the hook function modifies the current value it must
return TRUE, otherwise FALSE must be returned. If you return
TRUE, then the library will update the object. (V40)
This object type accepts all the GTST_#? tag items.
FRAME_KIND (fixed size general purpose display,
you may render into it):
LAFR_InnerWidth (LONG) - Inner width of the
display box.
LAFR_InnerHeight (LONG) - Inner height of the
display box.
LAFR_DrawBox (BOOL) - Draw a recessed bevel box
around the display box.
Default: FALSE
LAFR_RefreshHook (struct Hook *) - Hook to call
when refreshing/redrawing this object. See
gtlayout.h for more information. (V9)
LAFR_GenerateEvents (BOOL) - If TRUE, clicking
inside the FRAME_KIND object will generate
IDCMP_GADGETUP/IDCMP_GADGETDOWN events. If
you wish to know where the click occured,
make a copy of the Window->MouseX/Y entries
before you call LT_HandleInput()/LT_GetIMsg(). (V28)
Default: FALSE
GAUGE_KIND (general purpose progress report display):
LAGA_Percent (LONG) - Indicator position, can range
from 0..100.
Default: 0
LAGA_InfoLength (LONG) - Maximum number of characters
to reserve for text printed in the gauge display.
Default: 0
LAGA_InfoText (STRPTR) - Text to print in the gauge
display.
LAGA_Tenth (BOOL) - Instead of a continuously growing
bar you will get a set of exactly ten blocks,
each separated by a hairline. (V19)
Default: FALSE
LAGA_NoTicks (BOOL) - If TRUE suppresses drawing the
ticks below the gauge box.
Default: FALSE
IMAGE_KIND (display area for Image or BitMap data):
(requires gtlayout.library V41 or higher)
LAIM_Image (struct Image *) - Image to draw in this
place. When the user interface is built, it will
be drawn using intuition.library/DrawImage().
LAIM_BitMap (struct BitMap *) - You can supply a
BitMap instead of an Image which will be drawn
using either graphics.library/BltBitMapRastPort()
or graphics.library/BltMaskBitMapRastPort() if
a mask is provided.
LAIM_BitMapLeft (UWORD) - Left corner of the image data
to blit into the window (the second parameter for
BltBitMapRastPort()).
LAIM_BitMapTop (UWORD) - Top corner of the image data
to blit into the window (the third parameter for
BltBitMapRastPort()).
LAIM_BitMapWidth (UWORD) - Width of the bitmap area to
blit into the window.
LAIM_BitMapHeight (UWORD) - Height of the bitmap area to
blit into the window.
LAIM_BitMapMask (PLANEPTR) - Pointer to a bit plane mask
to blit the image bitmap through. Must follow the
rules documented for for BltMaskBitMapRastPort().
The blit operation will use the minterm for
transparency.
INTEGER_KIND:
LAIN_LastGadget (BOOL) - Pressing return with this
gadget active will stop activating the next
following string gadget type if TRUE is passed.
Default: FALSE
LAIN_Min (LONG) - Minimum accepted numeric value.
Default: -2147483647
LAIN_Max (LONG) - Maximum accepted numeric value.
Default: 2147483647
LAIN_UseIncrementers (BOOL) - Use TRUE to add incrementer
arrow buttons to the right of the numeric entry field.
These buttons will let you cycle through a set of
numbers to be displayed in the numeric entry field.
Default: FALSE
LAIN_HistoryLines (LONG) - Number of numbers entered to
keep as a backlog.
Default: 0
LAIN_HistoryHook (struct Hook *) - Hook code to call when
entering a number into the backlog. See gtlayout.h for
more information.
Default: NULL
LAIN_IncrementerHook (struct Hook *) - Hook code to call
when cycling through numeric values. See gtlayout.h for
more information.
Default: NULL
LAIN_Activate (BOOL) - When the window opens, make this
gadget the active one. (V21)
NOTE: There can be only one gadget of this type
per window.
Default: FALSE
LEVEL_KIND:
All tags are supported which SLIDER_KIND supports.
The gadget level display however, can only be aligned
to the left border.
LAVL_Freedom (WORD) - Selects the orientation of the
slider body; can be either FREEHORIZ or FREEVERT. (V41)
Default: FREEHORIZ
LAVL_Ticks (WORD) - Selects if and where to place tick
marks next to the slider body. Can be one of the
the following: TICKS_None (no ticks), TICKS_Left
(place ticks left of the body), TICKS_Above (place
ticks above the body), TICKS_Both (place ticks on
both sides of the body). (V41)
Default: TICKS_None
LAVL_NumTicks (LONG) - Number of tick marks to draw. (V41)
LAVL_Lines (LONG) - Height of the slider, if FREEVERT. (V41)
LISTVIEW_KIND:
LALV_ExtraLabels (STRPTR *) - Place extra line
labels at the right of the box. Terminate
this array with NULL.
LALV_Labels (STRPTR *) - The labels to display
inside the box, you can pass this array of
strings in rather than passing an initialized
List of text via GTLV_Labels. Terminate
this array with NULL.
LALV_CursorKey (BOOL) - Let the user operate this
listview using the cursor keys.
NOTE: there can be only one single listview
per window to sport this feature.
Default: FALSE
LALV_Lines (LONG) - The number of text lines this
listview is to display.
LALV_Link (LONG) - The Gadget ID of a string gadget
to attach to this listview.
NOTE: you need to
add the Gadget in question before you add the
listview to refer to it or the layout routine
will get confused.
Passing the value NIL_LINK will create a listview
which displays the currently selected item, otherwise
you will get a read-only list.
LALV_FirstLabel (LONG) - Locale string ID of the first
text to use as a list label. Works in conjunction
with LALV_LastLabel.
LALV_LastLabel (LONG) - Locale string ID of the last
text to use as a list label. Works in conjunction
with LALV_FirstLabel. When building the interface the
code will loop from FirstLabel..LastLabel, look
up the corresponding locale strings and use the
data to make up the label text to appear in the
list.
LALV_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the listview contents. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
LALV_MaxGrowX (LONG) - Maximum width of this object
measured in characters. When the first layout pass
is finished and there is still enough space left
to make the listview wider, the width is increased
until it hits the limit specified using this tag.
NOTE: there can be only one single listview
per window to sport this feature.
Default: 0
LALV_MaxGrowY (LONG) - Maximum height of this object
measured in lines. When the first layout pass is
finished and there is still enough space left to
make the listview higher, the height is increased
until it hits the limit specified using this tag.
NOTE: there can be only one single listview
per window to sport this feature.
Default: 0
LALV_ResizeX (BOOL) - Makes this listview resizable
in the horizontal direction, attaches a sizing
gadget to the window to open and handles window
resize operations automatically. (V9)
NOTE: there can be only one single listview
per window to sport this feature.
Also listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
Default: FALSE
LALV_ResizeY (BOOL) - Makes this listview resizable
in the vertical direction, attaches a sizing
gadget to the window to open and handles window
resize operations automatically. (V9)
NOTE: there can be only one single listview
per window to sport this feature.
Also listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
Default: FALSE
LALV_MinChars (WORD) - Minimum width for this
object, measured in characters. Used in
conjunction with LALV_ResizeX. (V9)
LALV_MinLines (WORD) - Minimum height for this
object, measured in lines. Used in
conjunction with LALV_ResizeY. (V9)
LALV_LockSize (BOOL) - After doing the initial layout
for this object, do not adapt its size again during
subsequent layouts. This is particularly useful if
you have a LISTVIEW_KIND object in a paged group
and keep adding new entries to the list. You need
to specify an object width using LA_Chars, otherwise
the layout engine may make it not wide enough to
display any entries. (V8)
LALV_FlushLabelLeft (BOOL) - For a gadget label placed
above the listview align the text to the left edge
of the view. (V9)
LALV_TextAttr (struct TextAttr *) - You can specify a
fixed-width font to be used for the list display.
The TextAttr (or TTextAttr) you provide must be ready
to go so the layout code can open the font later.
To get the current system default font, which is
guaranteed to be fixed-width, pass ~0 instead of a
pointer to a TextAttr structure. (V10)
NOTE: The font *MUST* be fixed-width or the layout
will fail.
Choose your font in such a way that it matches
in width and height with the other probably
proportional-spaced user interface font.
If the layout engine decides to step down in
font size, all LISTVIEW_KIND objects which were
configured to use a special fixed-width font
will `forget' about it. This won't matter much
as the fonts the engine chooses will always be
fixed-width anyway.
LALV_AutoPageID (LONG) - ID of paged GROUP_KIND object
which will be set to the gadget's current setting.
If this tag is set, you will hear no events from this
object any more. (V23)
NOTE: Listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
LALV_Selected (LONG) - In this context, this tag is an
alias for GTLV_Selected. See
gtlayout.library/LT_SetAttributes for more information
on how the meaning of this tag differs from this (V34).
MX_KIND:
LAMX_FirstLabel (LONG) - Locale string ID of the first
text to use as a label. Works in conjunction
with LAMX_LastLabel.
LAMX_LastLabel (LONG) - Locale string ID of the last
text to use as a label. Works in conjunction
with LAMX_FirstLabel. When building the interface the
code will loop from FirstLabel..LastLabel, look
up the corresponding locale strings and use the
data to make up the label text.
LAMX_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the radio labels. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
LAMX_TabKey (BOOL) - Connect this object to the tabulator
key. Press [Tab] to cycle to the next entry, [Shift][Tab]
to cycle to the previous entry. (V9)
NOTE: there can be only one single button per
window to use this feature.
Default: FALSE
LAMX_AutoPageID (LONG) - ID of paged GROUP_KIND object
which will be set to the gadget's current setting.
If this tag is set, you will hear no events from this
object any more. (V7)
NOTE: Listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
PALETTE_KIND:
LAPA_SmallPalette (BOOL) - Make the palette display
a bit smaller than usual.
Default: FALSE
LAPA_Lines (LONG) - Number of lines the palette
display should cover.
Default: No preference
LAPA_UsePicker (BOOL) - This tag effectively changes the
gadget type. Instead of a list of colours to pick from
the user will see a rectangle filled in the selected
colour with a picker button next to it. This gadget
will generate IDCMP_IDCMPUPDATE events when the picker
button is pressed. (V10)
PASSWORD_KIND (string gadget type which does not
display its contents):
LAPW_LastGadget (BOOL) - Pressing return with this
gadget active will stop activating the next
following string gadget type if TRUE is passed.
Default: FALSE
LAPW_HistoryLines (LONG) - Number of lines to keep as
a backlog.
Default: 0
LAPW_HistoryHook (struct Hook *) - Hook code to call
when entering a line into the backlog. See gtlayout.h
for more information.
Default: NULL
LAPW_Activate (BOOL) - When the window opens, make this
gadget the active one. (V21)
NOTE: There can be only one gadget of this type
per window.
Default: FALSE
This object type accepts all the GTST_#? tag items.
POPUP_KIND:
(This features requires gtlayout.library v22 or higher
and Kickstart 3.0 or higher).
LAPU_FirstLabel (LONG) - Locale string ID of the first
text to use as a label. Works in conjunction
with LAPU_LastLabel.
LAPU_LastLabel (LONG) - Locale string ID of the last
text to use as a label. Works in conjunction
with LAPU_FirstLabel. When building the interface the
code will loop from FirstLabel..LastLabel, look
up the corresponding locale strings and use the
data to make up the label text.
LAPU_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the cycle labels. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
LAPU_TabKey (BOOL) - Connect this object to the tabulator
key. Press [Tab] to cycle to the next entry, [Shift][Tab]
to cycle to the previous entry.
NOTE: there can be only one single button per
window to use this feature.
Default: FALSE
LAPU_AutoPageID (LONG) - ID of paged GROUP_KIND object
which will be set to the gadget's current setting.
If this tag is set, you will hear no events from this
object any more.
NOTE: Listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
LAPU_CentreActive (BOOL) - If TRUE, the popup menu will
appear with the currently active entry centred below
the mouse pointer. (V31)
LAPU_Labels (STRPTR *) - Pointer to NULL-terminated array
of strings that are the choices offered.
SCROLLER_KIND:
LASC_Thin (BOOL) - Make the scroller a bit thinner
than usual.
Default: FALSE
GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP
event from scroller.
Default: TRUE
NOTE: This is different from what
gadtools.library uses.
GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN
event from scroller
Default: TRUE
NOTE: This is different from what
gadtools.library uses.
SLIDER_KIND:
LASL_FullCheck: TRUE will cause the code to rattle
through all possible slider settings, starting
from the minimum value, ending at the maximum value.
While this may be a good idea for a display
function to map slider levels to text strings
of varying length it might be a problem when
it comes to display a range of numbers from
1 to 40,000: the code will loop through
40,000 iterations trying to find the longest
string.
FALSE will cause the code to calculate the
longest level string based only on the
minimum and the maximum value to check.
While this is certainly a good a idea when
it comes to display a range of numbers from
1 to 40,000 as only two values will be
checked the code may fail to produce
accurate results for sliders using display
functions mapping slider levels to strings.
Default: TRUE
STRING_KIND:
LAST_LastGadget (BOOL) - Pressing return with this
gadget active will stop activating the next
following string gadget type if TRUE is passed.
Default: FALSE
LAST_Link (LONG) - Gadget ID of the listview to attach
this string gadget to.
NOTE: you need to add the string gadget before
you add the listview to refer to it or the
layout routine will get confused.
LAST_Picker (BOOL) - Attach a `select' button to the
right hand side of the string gadget.
Default: FALSE
LAST_HistoryLines (LONG) - Number of lines to keep as
a backlog.
Default: 0
LAST_HistoryHook (struct Hook *) - Hook code to call
when entering a line into the backlog. See gtlayout.h
for more information.
Default: NULL
LAST_Activate (BOOL) - When the window opens, make this
gadget the active one. (V21)
NOTE: There can be only one gadget of this type
per window.
Default: FALSE
TAB_KIND:
(This features requires gtlayout.library v24 or higher)
LATB_FirstLabel (LONG) - Locale string ID of the first
text to use as a label. Works in conjunction
with LATB_LastLabel.
LATB_LastLabel (LONG) - Locale string ID of the last
text to use as a label. Works in conjunction
with LATB_FirstLabel. When building the interface the
code will loop from FirstLabel..LastLabel, look
up the corresponding locale strings and use the
data to make up the label text.
LATB_LabelTable (LONG *) - Pointer to an array of IDs
to use for building the cycle labels. This requires
that a locale hook is provided with the layout handle.
The array is terminated by -1.
LATB_TabKey (BOOL) - Connect this object to the tabulator
key. Press [Tab] to cycle to the next entry, [Shift][Tab]
to cycle to the previous entry.
NOTE: there can be only one single button per
window to use this feature.
Default: FALSE
LATB_AutoPageID (LONG) - ID of paged GROUP_KIND object
which will be set to the gadget's current setting.
If this tag is set, you will hear no events from this
object any more.
NOTE: Listen to IDCMP_CLOSEWINDOW events
which may be generated if the layout
engine runs out of memory when rebuilding
the user interface.
LATB_FullSize (BOOL) - By default a TAB_KIND object
covers the entire width of the group it sits in.
With LATB_FullSize set to true it will cover the
width of the entire Window.
Default: FALSE
LATB_Labels (STRPTR *) - Pointer to NULL-terminated array
of strings that are the choices offered.
TAPEDECK_KIND:
LATD_ButtonType (LONG) - Select the image to display
in the button, must be one of the following:
TDBT_BACKWARD
"<<" Symbol
TDBT_FORWARD
">>" Symbol
TDBT_PREVIOUS
"|<" Symbol
TDBT_NEXT
">|" Symbol
TDBT_STOP
Stop symbol (filled square)
TDBT_PAUSE
"||" pause symbol (broken square)
TDBT_RECORD
Record symbol (filled circle)
TDBT_REWIND
"<" symbol
TDBT_EJECT
Eject symbol (broken upward pointing arrow)
TDBT_PLAY
">" symbol
LATD_Toggle (BOOL) - Make this object a toggle-select
button.
Default: FALSE
LATD_Pressed (BOOL) - Make this button appear to be
pressed.
NOTE: requires "LATD_Toggle,TRUE" attribute.
Default: FALSE
LATD_Smaller (BOOL) - Make this button a bit smaller
than usual.
Default: FALSE
LATD_Tick (BOOL) - Hear IDCMP_GADGETUP events while the
buttons is being pressed; the IntuiMessage->Code entry
will be 0 while the button is being pressed, and
will be 1 as soon as the button is released. (V12)
Default: FALSE
TEXT_KIND:
LATX_Picker (BOOL) - Attach a `select' button to the
right hand side of the text display.
Default: FALSE
LATX_LockSize (BOOL) - After doing the initial layout
for this object, do not adapt its size again during
subsequent layouts. This is particularly useful if
you have a TEXT_KIND object in a paged group
and update its contents later. You need
to specify an object width using LA_Chars, otherwise
the layout engine may make it not wide enough to
display any text. (V15)
VERTICAL_KIND (group to align objects vertically):
HORIZONTAL_KIND (group to align objects horizontally):
LAGR_Spread (BOOL) - Place all objects in this
group with roughly the same amount of space
between them.
Default: FALSE
LAGR_SameSize (BOOL) - Make all objects in this
group the same size (for vertical groups:
the same height, for horizontal groups:
the same width).
Default: FALSE
LAGR_LastAttributes (BOOL) - Try to copy the
size of the previous group for this new
group. May not work if this group turns
out to be larger than the previous group.
Default: FALSE
LAGR_ActivePage (LONG) - Organize all child
groups as pages which can be flipped through
using LT_SetAttributes(). You need to
specify the number of the first page to
display, starting from 0.
NOTE: Specifying this tag actually enables
the paging feature. If you omit this
tag calls to flip to a specific
page will fail.
Default: No paging
LAGR_Frame (BOOL) - Draw a recessed frame around
this group, even if there is no group label. (V7)
LAGR_IndentX (BOOL) - Add extra horizontal indentation
for this group. (V10)
LAGR_IndentY (BOOL) - Add extra vertical indentation
for this group. (V10)
LAGR_NoIndent (BOOL) - Inhibit automatic size adjustion
and centring of this group if it is smaller than
the neighbouring groups. (V21)
LAGR_SameWidth (WORD) - During the final layout pass,
make this group the same width as the group which
uses the given ID. Not implemented yet. (V25)
LAGR_SameHeight (WORD) - During the final layout pass,
make this group the same height as the group which
uses the given ID. Not implemented yet. (V25)
LAGR_FrameGroup (UWORD) - Surround this group with a
frame. Must be one of FRAMETYPE_Label or FRAMETYPE_Tab.
FRAMETYPE_Label works like "LAGR_Frame,TRUE," while
FRAMETYPE_Tab is for use with a TAB_KIND object you
must put directly on top of this group or the group
will look a little silly. (V38)
Default: FRAMETYPE_None
XBAR_KIND (horizontal separator bar):
LAXB_FullSize (BOOL) - Make this separator bar span
the entire window width.
YBAR_KIND (vertical separator bar):
No tags are defined for this type of object.
RESULT
none
BUGS
Up to v25 the SCROLLER_KIND object did not support GA_Immediate
or GA_RelVerify. The space for the variables was there, but the
code was missing.
POPUP_KIND objects don't work well in simple refresh windows,
as refresh events can get lost. Use a smart refresh window
instead or call gadtools.library/LT_CatchUpRefresh() regularly.
SEE ALSO
gadtools.library/CreateGadgetA
gtlayout.library/LT_NewLevelWidth gtlayout.library/LT_NewLevelWidth
NAME
LT_NewLevelWidth -- Determine the maximum width of a SLIDER_KIND
level string. (V14)
SYNOPSIS
Index = LT_LevelWidth(Handle,FormatString,DispFunc,Min,Max,MaxWidth,
D0 A0 A1 A2 D0 D1 A3
MaxLen,FullCheck);
D3 D2
LONG LT_LevelWidth(LayoutHandle *,STRPTR,
LONG (*)(struct Gadget *,WORD),LONG,LONG,LONG *,
LONG *,BOOL);
FUNCTION
In order to make room for the level text displayed by a
SLIDER_KIND object one needs to know how much space the
longest level string will occupy. Otherwise, the level
text may overwrite the gadget label text or the slider
container. This routine will rattle through all possible
slider settings (as given via the Min and the Max
level values) and determine the longest label string
according to the font used.
INPUTS
Handle - Pointer to a LayoutHandle structure, as returned by
a call to LT_CreateHandleTags().
FormatString - The sprintf() style formatting string to be used
to format the slider level settings into text.
This is the same string you would pass in via
the GTSL_LevelFormat tag when creating the
slider object.
Default: "%lD" for systems which have locale.library
installed, "%ld" otherwise.
DispFunc - A pointer to the function to filter the slider level
values. The result of this function will then be
used to format a string into the slider level text.
This is the same parameter you would pass in via
the GTSL_DispFunc tag when creating the slider
object.
NOTE: the routine will be called with a NULL Gadget
parameter, make sure your code will handle
this nicely.
Default: no display function
Min - The smallest value the slider can be set to. This is
same value you would pass in via GTSL_Min when creating
the slider object.
Max - The largest value the slider can be set to. This is
same value you would pass in via GTSL_Max when creating
the slider object.
MaxWidth - Pointer to a place to store the width of the
longest level string in pixels. If you pass
in NULL instead of the address of a variable
no harm will be done.
MaxLen - Pointer to a place to store the length of the
longest level string in characters. If you pass
in NULL instead of the address of a variable
no harm will be done.
FullCheck - TRUE will cause the code to rattle through all
possible slider settings, starting from the
minimum value, ending at the maximum value.
While this may be a good idea for a display
function to map slider levels to text strings
of varying length it might be a problem when
it comes to display a range of numbers from
1 to 40,000: the code will loop through
40,000 iterations trying to find the longest
string.
FALSE will cause the code to calculate the
longest level string based only on the
minimum and the maximum value to check.
While this is certainly a good a idea when
it comes to display a range of numbers from
1 to 40,000 as only two values will be
checked the code may fail to produce
accurate results for sliders using display
functions mapping slider levels to strings.
RESULT
Index - The slider level which gives the longest
level string.
NOTES
This function does exactly what gtlayout.library/LT_LevelWidth
does, but uses a slightly different register ordering. Namely,
the MaxLen pointer is passed in D3 instead of A5.
SEE ALSO
gtlayout.library/LT_LevelWidth
gtlayout.library/LT_NewMenuTagList gtlayout.library/LT_NewMenuTagList
NAME
LT_NewMenuTagList -- Allocate and layout menu items (V11)
SYNOPSIS
Menu = LT_NewMenuTagList(Tags)
D0 A0
struct Menu *LT_NewMenuTagList(struct TagItem *);
struct Menu *LT_NewMenuTags(...);
FUNCTION
Allocates Menus and MenuItems similar to LT_LayoutMenus().
As of v18 this routine will validate menu mutual exclusion
information.
INPUTS
Tags - Pointer to a list of tagitem values, as found
in gtlayout.h
Valid tags include:
LAMN_Screen (struct Screen *) - Pointer to the Screen
the menu is to appear upon. This tag is mandatory,
unless the LAMN_LayoutHandle tag is used.
LAMN_TextAttr (struct TextAttr *) - Pointer to the
TextAttr to use for the menu layout. If this tag
is omitted the Screen->Font will be used.
LAMN_Error (LONG *) - Pointer to variable to receive
an error in case of failure.
LAMN_AmigaGlyph (struct Image *) - Pointer to Image to
use as the Amiga glyph in menus. Will be ignored if
NULL.
NOTE: Ignored by intuition.library v37 and below.
LAMN_CheckmarkGlyph (struct Image *) - Pointer to Image to
use as the checkmark glyph in menus. Will be ignored
if NULL.
LAMN_LayoutHandle (LayoutHandle *) - Pointer to a valid
LayoutHandle as created by LT_CreateHandle. This tag
provides all the information the single tags
LAMN_Screen..LAMN_CheckmarkGlyph would otherwise
need to provide.
LAMN_TitleText (STRPTR) - Name of new menu to create.
You may precede the name with the keyboard shortcut
to assign to this menu item as follows:
A\0Save as...
This will create a menu item using the shortcut "A"
and the title "Save as...".
LAMN_TitleID (LONG) - Locale ID corresponding to the
name of the new menu to create.
You may precede the name with the keyboard shortcut
to assign to this menu item as follows:
A\0Save as...
This will create a menu item using the shortcut "A"
and the title "Save as...".
LAMN_ItemText (STRPTR) - Name of new menu item to create.
You may precede the name with the keyboard shortcut
to assign to this menu item as follows:
A\0Save as...
This will create a menu item using the shortcut "A"
and the title "Save as...".
LAMN_ItemID (LONG) - Locale ID corresponding to the
name of the new menu item to create.
You may precede the name with the keyboard shortcut
to assign to this menu item as follows:
A\0Save as...
This will create a menu item using the shortcut "A"
and the title "Save as...".
LAMN_SubText (STRPTR) - Name of new submenu item to create.
You may precede the name with the keyboard shortcut
to assign to this menu item as follows:
A\0Save as...
This will create a menu item using the shortcut "A"
and the title "Save as...".
LAMN_SubID (LONG) - Locale ID corresponding to the
name of the new submenu item to create.
You may precede the name with the keyboard shortcut
to assign to this menu item as follows:
A\0Save as...
This will create a menu item using the shortcut "A"
and the title "Save as...".
LAMN_KeyText (STRPTR) - Pointer to the string whose first
character will be used as the keyboard shortcut for
this menu/submenu item.
LAMN_KeyID (LONG) - Locale ID corresponding to the string whose
first character will be used as the keyboard shortcut for
this menu/submenu item.
LAMN_CommandText (STRPTR) - Pointer to the string which
will be used as the keyboard shortcut for this
menu/submenu item.
LAMN_CommandID (LONG) - Locale ID corresponding to the string
which will be used as the keyboard shortcut for
this menu/submenu item.
LAMN_MutualExclude (ULONG) - Mutual exclusion information for
this menu/submenu item.
LAMN_UserData (APTR) - User data information for this
menu/menu item/submenu item.
LAMN_Disabled (BOOL) - Controls whether this
menu/menu item/submenu item should be disabled.
LAMN_CheckIt (BOOL) - Controls whether this menu/submenu item
should be prepared to hold a checkmark.
NOTE: This does not set the checkmark, use LAMN_Checked
for this purpose.
LAMN_Checked (BOOL) - Controls whether this menu/submenu item
should be marked with a checkmark. This tag implies
"LAMN_CheckIt,TRUE".
LAMN_Toggle (BOOL) - Controls whether this menu/submenu item
should be prepared to hold a checkmark the user is to
toggle on demand. This tag implies "LAMN_CheckIt,TRUE".
NOTE: this does not set the checkmark, use LAMN_Checked
for this purpose.
LAMN_Code (UWORD) - Raw key code to associate with this
menu/submenu item. To find out if a rawkey event
corresponds to this menu item use LT_FindMenuCommand.
LAMN_Qualifier (ULONG) - Key qualifier to associate
with this menu/submenu item.
NOTE: the comparison does not distinguish between
the left and right shift/caps/alt qualifier keys.
LAMN_ID (ULONG) - Unique ID to associate with this
menu/menu item/submenu item. You can use this
later to look up data using LT_GetMenuItem, etc.
LAMN_ExtraSpace (UWORD) - Number of pixels to put between
neighbouring menu titles. (V18)
Default: 0 pixels.
RESULT
Menu - Pointer to Menu structure, ready to pass to
SetMenuStrip(), NULL on failure.
EXAMPLE
The following tagitem list:
LAMN_TitleText, "Project"
LAMN_ItemText, "New",
LAMN_KeyText, "N",
LAMN_ItemText, "Open...",
LAMN_KeyText, "O",
LAMN_ItemText, NM_BARLABEL,
LAMN_ItemText, "Save",
LAMN_KeyText, "S",
LAMN_ItemText, "A\0Save As...",
LAMN_ItemText, NM_BARLABEL,
LAMN_ItemText, "Print...",
LAMN_KeyText, "P",
LAMN_ItemText, NM_BARLABEL,
LAMN_ItemText, "Help...",
LAMN_CommandText, "[Help]",
LAMN_ItemText, NM_BARLABEL,
LAMN_ItemText, "Quit...",
LAMN_KeyText, "Q",
TAG_DONE
Will create the following menu:
+-------+
|Project|
+-------+------+
|New aN|
|Open... aO|
|~~~~~~~~~~~~~~|
|Save aS|
|Save As... aA|
|~~~~~~~~~~~~~~|
|Print... aP|
|~~~~~~~~~~~~~~|
|Help... [Help]|
|~~~~~~~~~~~~~~|
|Quit... aQ|
+--------------+
NOTES
You may freely add, remove, spindle & mutilate the contents of the
menu strip created, just don't trash or disconnect the base menu
entry this routine creates as all menu memory tracking data is
connected to it.
SEE ALSO
gtlayout.library/LT_DisposeMenu
gtlayout.library/LT_FindCommandItem
gtlayout.library/LT_GetMenuItem
gtlayout.library/LT_LayoutMenuA
gtlayout.library/LT_MenuControlTagList
gtlayout.library/LT_NewMenuTemplate
intuition.library/SetMenuStrip
gtlayout.library/LT_NewMenuTemplate gtlayout.library/LT_NewMenuTemplate
NAME
LT_NewMenuTemplate -- Allocate and layout menu items (V11)
SYNOPSIS
Menu = LT_NewMenuTemplate(Screen,TextAttr,AmigaGlyph,CheckmarkGlyph,
D0 A0 A1 A2 A3
Error,MenuTemplate);
D0 D1
struct Menu *LT_NewMenuTemplate(struct Screen *,struct TextAttr *,
struct Image *,struct Image *,
LONG *,struct NewMenu *);
FUNCTION
Allocates Menus and MenuItems similar to LT_LayoutMenus().
As of v18 this routine will validate menu mutual exclusion
information.
INPUTS
Screen - Pointer to the screen the menu will appear on. This
parameter is required and must not be omitted.
TextAttr - Pointer to the TextAttr that should be used to
layout the menus. If this parameter is omitted,
Screen->Font will be used instead.
AmigaGlyph - Pointer to the Image to use as the Amiga glyph.
This parameter may be omitted.
NOTE: Ignored by intuition.library v37 and below.
CheckmarkGlyph - Pointer to the Image to use as the checkmark
glyph. This parameter may be omitted.
Error - Pointer to receive error code in case the menu
creation or layout process fails. This parameter
may be omitted.
MenuTemplate - Pointer to a series of NewMenu structures,
just as you would pass to
gtlayout.library/LT_LayoutMenuA.
RESULT
Menu - Pointer to Menu structure, ready to pass to
SetMenuStrip(), NULL on failure.
NOTES
The menu created by this function cannot be used with the
routines LT_MenuControlTagList, LT_FindMenuCommand and
LT_GetMenuItem.
You may freely add, remove, spindle & mutilate the contents of the
menu strip created, just don't trash or disconnect the base menu
entry this routine creates as all menu memory tracking data is
connected with it.
SEE ALSO
gtlayout.library/LT_DisposeMenu
gtlayout.library/LT_LayoutMenuA
gtlayout.library/LT_NewMenuTagList
intuition.library/SetMenuStrip
gtlayout.library/LT_PressButton gtlayout.library/LT_PressButton
NAME
LT_PressButton -- Highlight a button so it looks as if the user
has selected it.
SYNOPSIS
Success = LT_PressButton(Handle,ID);
D0 A0 D0
BOOL LT_PressButton(LayoutHandle *,LONG);
NOTE: The return value did not exist until V39!
FUNCTION
You can provide visual feedback for BUTTON_KIND objects by calling
this routine. They will briefly appear to be selected and then
fall back to their original states.
As of V39 and beyond this function will indicate whether the button
could be highlighted or not.
INPUTS
Handle - Pointer to LayoutHandle structure
ID - ID of button object to highlight
RESULT
Success (V39) - TRUE if button could be highlighted, FALSE otherwise.
gtlayout.library/LT_RebuildTagList gtlayout.library/LT_RebuildTagList
NAME
LT_RebuildTagList -- Rebuild the user interface after modifying it.
SYNOPSIS
Success = LT_RebuildTagList(Handle,Clear,TagList);
D0 A0 D0 A1
BOOL LT_RebuildTagList(LayoutHandle *,BOOL,struct TagItem *);
Success = LT_RebuildTags(Handle,Clear,...);
BOOL LT_RebuildTags(LayoutHandle *,BOOL,...);
FUNCTION
Certain aspects of the user interface can be changed at run time,
such as button labels. This routine will let you rebuild the interface
based upon the data supplied at creation time and your subsequent
changes. Before you make any vital changes, it is recommended to
lock the window using LT_LockWindow() in order to avoid clashes
with the Intuition and GadTools subsystems.
INPUTS
Handle - Pointer to LayoutHandle structure.
Clear - Pass in TRUE if you wish to have the window contents
cleared before they are rebuild. This will introduce
some visual hashing.
TagList - Attributes controlling the layout process.
Valid tags include:
LAWN_Bounds (struct IBox *) - Boundaries in which the window
should be centered.
LAWN_ExtraWidth (LONG) - Extra space to add to the window
width.
LAWN_ExtraHeight (LONG) - Extra height to add to the window
height.
RESULT
Success - TRUE indicates that the interface was rebuilt,
FALSE indicates trouble; it is recommended to
call LT_DeleteHandle() on your LayoutHandle as
soon as possible as the previous operation may
have left the user interface in an inoperable
state.
gtlayout.library/LT_Refresh gtlayout.library/LT_Refresh
NAME
LT_Refresh -- Redraws the entire window contents.
SYNOPSIS
LT_Refresh(Handle)
A0
VOID LT_Refresh(LayoutHandle *);
FUNCTION
Redraws the contents of the window, this includes both gadgets
and imagery.
INPUTS
Handle - Pointer to a LayoutHandle structure.
RESULT
none
SEE ALSO
gadtools.library/GT_RefreshWindow
intuition.library/RefreshGList
gtlayout.library/LT_ReplyIMsg gtlayout.library/LT_ReplyIMsg
NAME
LT_ReplyIMsg -- Dispose of an IntuiMessage received
SYNOPSIS
LT_ReplyIMsg(IntuiMessage);
A0
VOID LT_ReplyIMsg(struct IntuiMessage *);
FUNCTION
This routine complements LT_GetIMsg().
INPUTS
IntuiMessage - Pointer to IntuiMessage structure,
passing NULL is harmless.
RESULT
none
NOTES
Only pass IntuiMessages you received via LT_GetIMsg,
or things will get tough.
SEE ALSO
gtlayout.library/LT_GetIMsg
gtlayout.library/LT_SetAttributesA gtlayout.library/LT_SetAttributesA
NAME
LT_SetAttributesA -- Change object attributes
SYNOPSIS
LT_SetAttributesA(Handle,ID,Tags);
A0 D0 A1
VOID LT_SetAttributes(LayoutHandle *,LONG,struct TagItem *);
LT_SetAttributes(Handle,ID,...);
VOID LT_SetAttributes(LayoutHandle *,LONG,...);
FUNCTION
This routine passes the tag item list it gets directly
over to GT_SetGadgetAttrsA(), so any tag items valid for
gadtools.library can be used here as well. Some filtering
may be done in order to stop objects from getting redrawn
if this is not absolutely necessary.
INPUTS
Handle - Pointer to LayoutHandle.
ID - ID number of the object to change. This is the same value
you passed via LA_ID to LT_New() when you created this object.
Tags - Attributes controlling object states.
All gadtools.library tags are allowed, but not all are supported.
In addition to these tags a few additional tag values are
supported:
LAHN_AutoActivate (BOOL) - Set to TRUE if you want the interface
to always keep a string gadget active if possible. Hitting
the return key will then cause the next following string
gadget to get activated, either cycling through all the
string gadgets available or stopping at the next string
gadget to have the LAST_LastGadget attribute set.
LAHN_UserData (APTR) - Store user specific data in the
LayoutHandle->UserData entry. (V9)
LAHN_RawKeyFilter (BOOL) - Discard unprocessed IDCMP_RAWKEY
events. (V13)
Default: TRUE
LAHN_LocaleHook (struct Hook *) - The hook to call when
locale string IDs are to be mapped to strings. The
hook function is called with the following parameters:
String = HookFunc(struct Hook *Hook,struct LayoutHandle *Handle,
D0 A0 A2
LONG ID)
A1
The function is to look up the string associated with the ID
passed in and return the string.
LAHN_ExitFlush (BOOL) - When the LayoutHandle is finally disposed
of with LT_DeleteHandle() all variables maintained by the
input handling code will be flushed. For example, if you
would use the LA_STRPTR tag for STRING_KIND objects the
last string gadget contents would be copied into the buffer
pointed to by LA_STRPTR. If you do not want to use this
feature, disable it with "LAHN_ExitFlush,FALSE". (V9)
Default: TRUE
GAUGE_KIND:
LAGA_Percent (LONG) - Percentage of the gauge to fill.
LAGA_InfoText (STRPTR) - Text to be printed within the
gauge display, such as a percentage number.
BOX_KIND:
LABX_Index (LONG) - The number of the line to change, this
tag works in conjunction with the LABX_Text tag.
LABX_Text (STRPTR) - The text to put into the line indicated
by the LABX_Index tag.
As of v26 the LABX_Index tag may be omitted, the library
will then assume the line index will be 0.
LABX_Lines (STRPTR *) - The text to set for the box contents,
terminate the text array with NULL.
HORIZONTAL_KIND:
VERTICAL_KIND:
LAGR_ActivePage (LONG) - Index number of page to display
within the group.
NOTE: requires that this group was created
with the LAGR_ActivePage attribute set.
INTEGER_KIND:
LAIN_Min (LONG) - Minimum allowed value for this
object.
LAIN_Max (LONG) - Maximum allowed value for this
object.
LISTVIEW_KIND:
LALV_Selected (LONG) - Combines GTLV_Selected and
GTLV_Top (for Kickstart V37) or GTLV_MakeVisible
(for Kickstart V39 and greater). This means, the
list display will be changed in order to show
the item to be selected. (V34)
LEVEL_KIND:
LAVL_NumTicks (WORD) - Number of tick marks to draw
next to the slider body.
PASSWORD_KIND:
LAPW_String (STRPTR) - Secret text to use
POPUP_KIND
LAPU_Labels (STRPTR *) - To block access to the popup
menu, for example before you free the current list
of labels, you can pass ~0 as the list parameter. (V25)
STRING_KIND:
LAST_CursorPosition (LONG) - Repositions the cursor,
pass -1 to move it to the end of the string. (V7)
TAPEDECK_KIND:
LATD_Pressed (BOOL) - TRUE to make this button shown
as pressed, FALSE to show it in depressed state.
BOOPSI_KIND:
All tags are passed straight through to SetGadgetAttrs(..).
All objects:
LA_LabelText (STRPTR) - New gadget label text to use.
LA_LabelID (LONG) - Locale text ID to use for this object.
RESULT
none
SEE ALSO
gadtools.library/GT_SetGadgetAttrsA()
intuition.library/SetGadgetAttrsA
gtlayout.library/LT_ShowWindow gtlayout.library/LT_ShowWindow
NAME
LT_ShowWindow -- Make a window visible
SYNOPSIS
LT_ShowWindow(Handle,Activate);
A0 A1
VOID LT_ShowWindow(LayoutHandle *,BOOL);
FUNCTION
The window attached to a LayoutHandle is made visible, this
involves bringing it to the front, bringing the screen to
the front the window resides on, unzooming the window and
also moving the visible part of an autoscrolling screen.
INPUTS
Window - Pointer to Window structure.
Activate - If TRUE the window will be activated as soon
as it has been brought to the front.
RESULT
none
NOTES
The arguments are passed in A0 and A1, this is *not* a
typo.
BUGS
In revisions earlier than v21 this routine consistently
failed to reliably unzip a window in zoomed state. This
could cause the calling application to wait for about
five seconds before continuing execution.
SEE ALSO
intuition.library/MoveScreen
intuition.library/ScreenPosition
intuition.library/ZipWindow
gtlayout.library/LT_UnlockWindow gtlayout.library/LT_UnlockWindow
NAME
LT_UnlockWindow -- The complement to LT_LockWindow().
SYNOPSIS
LT_UnlockWindow(Window);
A0
VOID LT_UnlockWindow(struct Window *);
FUNCTION
This routine unlocks a window locked using LT_LockWindow, freeing
allocated memory, restoring the window characteristics to their
original values.
INPUTS
Window - Pointer to window structure; passing NULL is harmless.
RESULT
none
SEE ALSO
gtlayout.library/LT_LockWindow
gtlayout.library/LT_UpdateStrings gtlayout.library/LT_UpdateStrings
NAME
LT_UpdateStrings -- Make sure all visible string buffer contents
get written into storage (v9).
SYNOPSIS
LT_UpdateStrings(LayoutHandle);
A0
VOID LT_UpdateStrings(struct LayoutHandle *);
FUNCTION
The user can terminate input into a string gadget or an object
derived from a string gadget by various means. They all have
in common that the application receives no notification that
the string gadget contents have changed. This is particularly
nasty with objects which make use of LA_STRPTR or other
tags. Using LT_UpdateStrings() you can force all visible string
gadget objects to hand over their contents to the internal
buffers. Do this before you eventually exit your input loop.
INPUTS
LayoutHandle - Pointer to LayoutHandle structure.
RESULT
none